Mac OS X Developer Preview 4 Release Notes Copyright © 1999, 2000 by Apple Computer, Inc. All Rights Reserved.
The notes below are split into the following sections:
Aqua
The big change in Developer Preview 3 is Aqua,
the new user interface. Aqua brings
with it a lot of visual changes, new features, and many additions to the APIs.
Although you get the new look for Aqua
automatically in your applications, some of the new features such as document
modal panels are accessible via new APIs and are not automatically picked up.
For the most part, Aqua metrics are larger than
those used previously (in the Mac OS X Server "platinum" look). This
means that when pre-Aqua nib files are opened up under Aqua, certain controls
will be clipped. In addition, Aqua
introduces a new layout for the menu bar.
See below for details on how to convert nibs
to Aqua guidelines.
Preliminary UI guidelines for Aqua can be found
in AquaLayoutGuidelines.pdf.
Platform-specific Resource Modifiers
In order to allow pre-Aqua and Aqua interfaces
to co-exist, we have separate resource modifiers for the platinum appearance
(used on Mac OS X Server) and Aqua. Use macintosh for the Mac OS X
Server look, and macos for Aqua. You do this by appending
"-macos" or "-macintosh" to the base name of any resource
obtained (directly or indirectly) via NSBundle or CFBundle.
For those of you converting resources to
support Aqua, but also needing to support the Mac OS X Server look, we suggest
renaming your old resources to have the macintosh platform identifier,
and saving youre the Aqua resources without a platform identifier. This is
probably as simple as:
cp -r
foo.nib foo-macintosh.nib
now edit foo.nib to for Aqua
(Things will get a bit trickier if you have
other platform-specific resources.)
If you do not need to support Mac OS X Server,
then you can simply have one set of nibs, with no special resource identifiers.
Interface Builder provides a convenience for
upgrading nibs to conform to Aqua guidelines. Open your nib files in IB, and
use the "Apply UI Guidelines" menu command to fix up windows and
menus.
Apply UI Guidelines applies only to the
currently selected editing window; so if you have multiple windows in your nib,
you will need to select each window by hand and perform this command. In
addition, to fix up your menu layout, click on the menu editor (the on-screen
representation of the menu, not the MainMenu image in the IB document window)
and perform this command.
In many cases you might need additional tweaks
to fix things up.
In old nib files, controls might not be using
the "Message" font, but instead a hardwired font such as Helvetica.
These are not automatically converted to use Lucida at 14 point, which is the
new default font for most controls. In
those cases it's best to set the font used by those controls to "User's
Message Font," at 14 pt, selectable via the font panel in Interface Builder.
Drawer
Drawers are a new addition to the AppKit. For an example of a drawer, see the
mailboxes drawer in Mail. From an API
perspective, NSDrawer is a peer of NSWindow; like a window, a drawer is used to
contain and display views. A drawer,
however, can appear on screen only when associated with a window, which is
called its parent. A drawer cannot be
moved or ordered independently, but instead is attached to one of the edges of
its parent, and moves along with it.
Drawers may be resized, but a drawer can never be larger than its
parent. A given window may have any
number of drawers; it is the developer's responsibility to make sure that
multiple drawers are not open at once overlapping each other on the same edge.
A drawer may be either open or closed, or in
the process of opening or closing. When
a drawer is closed, it does not appear on screen. A drawer may be opened on a particular edge of its parent; a
drawer also has a preferred edge, which is used when it is told to open without
an edge being specified. The opening or
closing of a drawer does not happen instantaneously, so a notification is sent
whenever a drawer has finished opening or closing. However, a drawer may be told to open or close at any time, with
the expectation that the command will eventually be carried out. If a rapid series of open and close commands
is issued, the last one may supersede the others, and in any case will
determine what state the drawer finally ends up in.
The precise appearance of the drawer, and its
implementation, may be platform-dependent.
When a drawer is on screen, its views must necessarily be placed within
some NSWindow so that they can be displayed, but this object is private and its
precise class is likely to be platform-dependent. The NSDrawer API concentrates on the content area of the drawer
rather than on its border or frame.
Methods are available to create a drawer, to
supply it with a content view and a preferred edge, and to associate it with a
parent:
-
(id)initWithContentSize:(NSSize)contentSize preferredEdge:(NSRectEdge)edge;
-
(void)setParentWindow:(NSWindow *)parent;
-
(NSWindow *)parentWindow;
-
(void)setContentView:(NSView *)aView;
-
(NSView *)contentView;
-
(void)setPreferredEdge:(NSRectEdge)edge;
-
(NSRectEdge)preferredEdge;
Note that the parent window will retain the
drawer, and not vice versa. A drawer
may be disassociated from any parent by setting its parent window to nil, but
in that case the drawer would need to be explicitly retained if it is still
needed. Also, a drawer without a parent
cannot be opened. If setParentWindow:
is sent to a drawer that is not closed, the change will take effect only when
the drawer is next closed.
Methods are also provided to open or close a
drawer, and to ascertain its state:
-
(void)open;
-
(void)openOnEdge:(NSRectEdge)edge;
-
(void)close;
-
(NSDrawerState)state;
-
(NSRectEdge)edge;
Methods are provided to set the size of a
drawer, or to set minimum and maximum sizes for it, but these do not override
the rule that a drawer cannot be larger than its parent.
-
(void)setContentSize:(NSSize)size;
-
(NSSize)contentSize;
-
(void)setMinContentSize:(NSSize)size;
-
(NSSize)minContentSize;
-
(void)setMaxContentSize:(NSSize)size;
-
(NSSize)maxContentSize;
An open drawer is attached precisely to the
appropriate edge of its parent window, but its position and size along that
edge may be controlled, relative to the content area of its parent, with a
leading and trailing offset. If these
parameters are not set, default values will be supplied that are appropriate
for the current interface style. These
offsets may not be negative.
-
(void)setLeadingOffset:(float)offset;
-
(float)leadingOffset;
-
(void)setTrailingOffset:(float)offset;
-
(float)trailingOffset;
Font Panel
The Font Panel user interface has been
considerably enhanced in this release.
The panel now has three panes (Fonts, Favorites, Edit Collections).
The main view of the panel is now a
three-column browser, with the left-most column being a list of named font
collections. The other two columns are
the familiar family and typeface columns. The size scrolling list is
unchanged. Selecting an element in this
browser now causes immediate update of whatever portions of the document are
selected, as well as update of the preview area. Prior releases required the user to hit a button to set the
document's font.
The Edit Collections view allows the user to
select a collection, view its members, and add or remove members with the
<< and >> buttons. Users
can also create new collections or delete existing collections.
The Favorites view is simply a list of fonts
that can be set with one click, including their size. Names of favorite entries are given descriptive default names,
but can be edited by the user.
Currently, changes made to collections or
favorites are not propagated to other running applications, but changes are
only picked up globally by logging out and logging in again. This is intended
to be fixed in an upcoming release.
Note: Developers who subclass the font panel must
recompile their subclasses; the object size and layout has been changed
drastically to accommodate the new functionality. Instance variables have been updated, and some old, unused
variables have been removed.
The accessory view, if used, appears at the
very bottom of the panel, below the buttons, instead of being embedded within
the panel above the buttons.
There
is a new method reloadDefaultFontFamilies in the font panel. This is a
"trigger" method intended only for use by delegates. It causes the
font panel to reload the set of default font families. When the re-load
operation occurs, the delegate will be called for each family, as documented,
and have the opportunity of deciding whether the family should be included or
not. This is intended to fix the problem that one cannot set the delegate of a
font panel without having instantiated it, so at the time of original
instantiation, the delegate has no chance to examine the families.
Application
The NSApplicationDidFinishLaunchingNotification
is now sent at a slightly different time.
Handling of opening or printing files or of opening an untitled document
during application launching used to be handled prior to the main event loop
starting up. Because the AppleEvents
for 'oapp', 'odoc', and 'pdoc' are received through the main event loop as the
first event when an application starts running, if we send the
NSApplicationDidFinishLaunchingNotification right before entering the main
event loop, that notification will happen before documents are opened. To avoid this, the notification is now sent
immediately after handling the 'oapp', 'odoc', or 'pdoc' event during the first
pass through the loop.
This change should actually preserve what most
observers of this notification expect: it will still be sent after the
application has finished launching and opened any initial documents. But it is now sent after the run loop has
been cycled once and the first event (the launch-time AppleEvent) has been
handled.
Document Modal Panels
Mac OS X introduces the concept of document modal
panels ("sheets"). A document
modal panel causes the document to which it refers to enter a modal state,
without putting the entire application into a modal state. The document modal panel is referred to as a
sheet and has a special appearance and behaves as if it were attached to the
document window. API has been added to
support creation of document modal panels.
The application may implicitly create and run
an alert panel with a variant of NSRunAlertPanel, which takes a document window
to which the modal panel refers:
int
NSRunAlertPanelRelativeToWindow(NSString *title, NSString *msg, NSString
*defaultButton, NSString *alternateButton, NSString *otherButton, NSWindow
*docWindow, ...);
int
NSRunInformationalAlertPanelRelativeToWindow(NSString *title, NSString *msg,
NSString *defaultButton, NSString *alternateButton, NSString *otherButton,
NSWindow *docWindow, ...);
int
NSRunCriticalAlertPanelRelativeToWindow(NSString *title, NSString *msg,
NSString *defaultButton, NSString *alternateButton, NSString *otherButton,
NSWindow *docWindow, ...);
After an application creates a modal panel, one
of two methods in NSApplication may be used to run it in a document modal
state:
-
(int)runModalForWindow:(NSWindow *)theWindow relativeToWindow:(NSWindow
*)docWindow;
-
(NSModalSession)beginModalSessionForWindow:(NSWindow *)theWindow
relativeToWindow:(NSWindow *)docWindow;
If the position of the document window at sheet
creation time would cause the sheet to be partially offscreen, the parent is
moved on screen in order to fully display the sheet. When the sheet is dismissed, the parent is moved back to its
original position.
SavePanel
There is a new method that allows the save
panel to be presented as a sheet. -[NSSavePanel
runModalForDirectory:file:relativeToWindow:] takes as its third parameter, a
window. If this parameter is not nil, then save panel slides down as a sheet
running as a document modal window. Passing in nil defaults to a standalone
modal panel.
Note that if your pre-Aqua default save panel
size was very small, there may be problem with the initial layout of some items
in the panel. You can remove the old saved default size by typing the following
in Terminal to reset to the initial default size:
defaults delete NSGlobalDomain "NSWindow Frame NXSavePanel"
NSSavePanel has changed size, so any
subclassers will need to be recompiled.
Menu
The implementation of menus has changed drastically; NSMenuView and
NSMenuItemCell are no longer used, -[NSMenu
menuRepresentation]
now returns nil, and tear off menus are no longer available. For Developer
Preview 3, there is no support for menu item images. If there is no text in the
menu item, a placeholder text consisting of "<image>" or
"<image name>" will be inserted instead. Menu item state
images are not supported either and in their place the standard checkbox or
dash for on and mixed states are used.
Dock Miniaturization
On Mac OS X, miniaturizing a window causes a
thumbnail of the window to appear in the dock.
Calling -[NSWindow miniaturize:] will cause the target window to animate
(genie) into a thumbnail, and -[NSWindow deminiaturize:] will re-expand the
window. The title of the thumbnail
should be brief, and is set by calling -[NSWindow setMiniwindowTitle:]. If the thumbnail has not been named via
setMiniwindowTitle:, an abbreviation of the window title will be used.
In DP3, operations involving the dock may cause
the runloop to be reentered in ways your application does not expect (for example,
timers might fire). These operations include -[NSWindow setMiniwindowTitle:],
-[NSWindow setTitle:] (if you do not explicitly call setMiniwindowTitle:),
-[NSWindow miniaturize:], and -[NSWindow deminiaturize:]. We will be looking at
ways to prevent this reentrancy in the future, but for now you may need to
safeguard against it.
Continuous Spelling Checks
There are three new methods in NSTextView.h:
-
(void)setContinuousSpellCheckingEnabled:(BOOL)flag;
-
(BOOL)isContinuousSpellCheckingEnabled;
-
(void)toggleContinuousSpellChecking:(id)sender;
These turn on and off continuous (as-you-type)
spellchecking. In addition,
NSTextView's context menu will allow you to correct a selected misspelled
word. There is also a new method in
NSSpellChecker.h:
-
(NSArray *)guessesForWord:(NSString *)word;
This allows programmatic access to the list of
suggested corrections for a given word.
Box
There is a new NSBoxType that overrides the
existing border types.
typedef
enum {
NSBoxPrimary = 0, // default
NSBoxSecondary = 1,
NSBoxSeparator = 2,
NSBoxOldStyle = 3 // use border type
}
NSBoxType;
By default, a new NSBox has a box type of
NSBoxPrimary. If the box type is NSBoxSeparator, then a separator line is drawn
centered in the box parellel to the longest side. If the box style is
NSBoxOldStyle, then the border type is used instead. In all cases, if the
border type is NSNoBorder, no box is drawn.
-
(void)setBoxType:(NSBoxType)boxType;
-
(NSBoxType)boxType;
Window
There is new API to turn shadows on and off on
a per window basis:
-
(void)setHasShadow:(BOOL)hasShadow;
-
(BOOL)hasShadow;
Changing the shadow state affects the window
immediately. You can also override hasShadow. The default is that all windows
except borderless ones have a shadow.
Pattern Color
NSColor now contains support for patterned
colors made from NSImages:
+
(NSColor *)colorWithPatternImage:(NSImage*)image;
-
(NSImage *)patternImage;
The NSImage is retained by the pattern color.
There is also a new color space,
NSPatternColorSpace, to go along with this feature.
The pattern is always aligned to the bottom of
the window. Use the CoreGraphics call CGSetHalftonePhase() to change the phase
of the pattern.
System NSColors do not yet support the patterns
used by Aqua. However, a new function has been added to draw the Aqua window
background pattern. You can use this for custom controls so that the control
doesn't need to be transparent:
void
NSDrawWindowBackground(NSRect aRect);
This assumes the current view is in a window
and adjusts the pattern so that it is always aligned with the top of the
window.
Control Tints
You can specify whether NSCell, NSTabView, and
NSScroller have a tinted or clear appearance when the window is active. The
currently valid tints defined in NSCell.h are:
typedef
enum _NSControlTint {
NSDefaultControlTint = 0, // system 'default'
NSClearControlTint = 7
}
NSControlTint;
The new methods in these three classes are:
-
(void) setControlTint:(NSControlTint)controlTint;
-
(NSControlTint)controlTint;
Autoscroll while dragging
NSClipView now implements autoscrolling while
dragging. Autoscrolling starts when the
cursor is held within 5 pixels from the edges for 0.3 seconds.
SplitView
The appearance of NSSplitView has changed;
horizontal splits are drawn transparent with a two-line grabber in the
center. Vertical splits currently are
drawn completely transparent; this is expected to change before the final
release of MacOS X. In addition, there
is new API on NSSplitView to change a horizontal split view's appearance from
the transparent version seen in the Font Panel to the bubbled, opaque one seen
in Mail. The new methods are
-setIsPaneSplitter: and -isPaneSplitter; the bubbled, opaque appearance is the
pane splitter appearance (i.e. the split view used by Mail returns YES from
isPaneSplitter).
Interface Builder allows you to choose between
the two splitter types through the split view inspector.
Split views also now dynamically resize their
subviews as the thumb is dragged. One side effect of this is that NSSplitView's
delegate methods and notifications pertaining to resizing are sent much more
often as the drag is performed. This could result in a noticeable performance
impact if the methods or notifications cause time-intensive routines to be
called.
NSUserInterfaceValidation
This new protocol defines the generic and
standard user interface validation mechanism. Currently NSMenuItem is the only client
of this protocol. Please refer to comments in NSUserInterfaceValidation.h for
details.
Document
A new method called noteNewRecentDocument: has
been added to NSDocumentController.
This method is similar to noteNewRecentDocumentURL: except that the
NSDocument instance is passed to it.
The default implementation gets the URL from the document and calls
noteNewRecentDocumentURL:. This new
method is always invoked by NSDocument instead of noteNewRecentDocumentURL: and
it has been added to provide a better override point for NSDocument based apps
that wish to have a chance to leave some documents out of the recents
list. Making this decision based on the
NSDocument instance is often more convenient than having to base it on the URL.
Non NSDocument-based apps can and should still
call noteNewRecentDocumentURL: to get the recent documents feature for their
applications.
BezierPath
NSBezierPath methods
appendBezierPathWithPackedGlyphs: and drawPackedGlyphs:atPoint: are now
implemented.
String Drawing
NSParagraphStyleAttributeName now does the
correct thing regardless of flippedness of the focused view.
StatusBar
Because of UI changes, status bar items are no longer drawn on the screen in
Developer Preview 3 even though the API has not changed. A replacement will be
made available in a subsequent release.
TableView
Because of additional drawing required, the clip view that contains the
contents of a table view has it's copiesOnScroll flag set to NO
at this time. This may affect scrolling performance for large table views.
Cocoa Framework
DP2 includes the concept of "umbrella frameworks," a small number of public frameworks which simply link against other frameworks. The idea is for applications to link against these umbrella frameworks rather than their individual components, which will make it easier for the underlying list of implementation frameworks to be changed.
One of these umbrella frameworks is Cocoa.framework, which currently includes AppKit and Foundation, but in the future will be expanded to include the scripting frameworks.
Other umbrella frameworks are Carbon, ApplicationServices (common UI level services), CoreServices (CoreFoundation, CarbonCore, and other UI-free common services), and System (Posix, BSD, and Mach APIs).
Application Packaging
The new application package structure is outlined in the CFBundle/CFPlugIn release notes. The old structure will continue to work, but it is recommended that you convert your application to the new structure as it is the format NSBundle first checks for when looking for resources.
In DP2, on "make install," the Project Builder makefiles will still create an old-style package. However, you can add the following to your Makefile.preamble to cause the new style package to be built:
BUNDLE_STYLE = MACOSX
This will cause the script /System/Developer/Makefiles/pb_makefiles/convertBundle to be run at the end of "make install" to convert your application's app package to the new style. Note that if you run "make install" as yourself and not as root, this script might fail.
If your application package needs to work on MacOS X Server, or you have some code that rummages through the application wrapper without going through NSBundle or CFBundle APIs, you might not be able to switch to the new format immediately.
Application and Document Icons
In DP2, Finder expects application and document icons in the ICNS format. TIFF does not work. The following describes the steps needed to create ICNS versions of your icons and get them incorporated into your project.
Note that you need to do this only for the icons displayed by Finder. Most of the TIFF images in your application do not need to be converted.
You can use the tool /usr/bin/tiff2icns to convert your TIFF icons to ICNS format. ICNS, like TIFF, supports multiple formats in one file, and the conversion should preserve all the images in the TIFF, in addition to creating a 1-bit hit mask that the Finder requires.
The tool will reduce the 48 x 48 image in the TIFF to 32 x 32 if the TIFF doesn’t have a 32 x 32 format. If the TIFF has a 16 x 16 image, and it’s deeper than the 48 x 48, the tool might choose to expand that one instead. If you notice that the 32 x 32 image in the ICNS is blurry (which will be the case if it was scaled from the 16 x 16), you might want to extract the 48 x 48 icon into its own TIFF file and then do the conversion. You can use "tiffutil -info" to enumerate the images in the TIFF and "tiffutil -extract" to extract the correct one.
Once you have your ICNS files, add them to your app project as non-localizable (or localizable, if they need to be localized) resources. Then, in ProjectBuilder's project inspector, go to the "Project Attributes" panel. Delete all of the extension / icon name pairs as these are not used anymore. Do not delete the entry for "App Icon"; this image is still used by [NSImage imageNamed:@"NSApplicationIcon"] as the icon for your application within your application.
Finally, you need to add some new keys to your CustomInfo.plist file. If you don't already have a CustomInfo.plist file, you will need to create one (in the "Supporting Files" bucket).
For your application icon, simply include an entry for CFBundleIconFile. For each document type the app supports, include an entry in the array CFBundleDocumentTypes. If your app supports no documents, put an empty array here.
You can look at TextEdit’s CustomInfo.plist file (/System/Developer/Examples/AppKit/TextEdit/CustomInfo.plist) as a sample. TextEdit declares four document types; 3 of which it can edit, one of which (html) it can just view. The "*" extension indicates that TextEdit is willing to open files with any extension. Most apps do not need this. For the types that are known to the system, the pasteboard name is used as the value of CFBundleTypeName. For other types (such as html in the above example), this entry can be an arbitrary string, ideally prefixed with your company name to assure uniqueness.
The InfoPlist release note has more details on the various keys and their values.
InterfaceBuilder
IB now supports NSTableView and NSOutlineView. Please refer to InterfaceBuilder release notes for more info.
Document / DocumentController
It is now easier to subclass NSDocumentController by instantiating a subclass in your main nib. Interface Builder has certain problems in test interface mode if you use such a subclass, but they are cosmetic.
NSDocument's -readFromFile: now resolves symlinks in the filename.
A couple new methods that allow more advanced access to the saving facility to allow access to the original backed up document and control over the actual backup process have been added.
NSWindowController is now a subclass of NSResponder. This is a binary and source compatible change for both Objective-C and Java. In addition, and NSWindowController automatically installs itself as the -nextResponder of its window. What this means is that an NSWindowController subclass can implement responder methods like keyDown: and receive them as any responder in the chain normally would.
Recent Documents
Support for an "Open Recent" menu has been added. NSDocument based apps will get this new menu automatically. Non-NSDocument apps will have to add this menu and call NSDocumentController's noteNewRecentDocumentURL: method to get items to appear in it.
QuickDrawView
A new flipped, non-opaque view has been added to Cocoa that will allow you to draw using Carbon QuickDraw. Whenever a lockFocus call on the view is made (such as just before -[NSQuickDrawView drawRect:]), a QuickDraw CGrafPort will have been created and set. The port frame reflects the visible bounds of the view and may change between calls. You can get the view's CGrafPtr by calling -[NSQuickDrawView qdPort] though it is only valid when inside a lockFocus/unlockFocus. Also note that it creates a CGrafPort for each view.
ToolTips
NSView is now capable of more sophisticated tooltip control, introduced with the following three methods:
- (NSToolTipTag)addToolTipRect:(NSRect)aRect owner:(id)anObject userData:(void *)data;
- (void)removeToolTip:(NSToolTipTag)tag;
- (void)removeAllToolTips;
If NSView detects that a tooltip rectangle has been activated, it sends the owner the following method to obtain the string to display:
- (NSString *)view:(NSView *)view
stringForToolTip:(NSToolTipTag)tag point:(NSPoint)point userData:(void *)data;
In addition NSMatrix now supports per-cell tooltips:
- (void)setToolTip:(NSString *)str forCell:(NSCell *)cell;
- (NSString *)toolTipForCell:(NSCell *)cell;
TableView
A new method, dataCellForRow:, has been added to NSTableColumn to manage the cell used to draw the actual values in a table view. NSTableView now always calls dataCellForRow:, which, by default just calls the method dataCell. Subclassers can override this if they need to potentially use different cells for different rows. Subclassers should be prepared to handle row == -1 in cases where no actual row is involved but the table view needs to get some generic cell info.
Carbon
All Cocoa applications now bring in the Carbon libraries, which means that the public symbols in these libraries appear in the same name space as the application. Most of the public symbols in Carbon do not use prefixes, which makes it possible for there to be symbol conflicts. The solution to this is to avoid the conflicts by renaming your symbols.
Performance
Because of large underlying changes in the system since MacOS X Server, it is possible that some performance problems have been introduced into your application. Most of these are in the underlying libraries and system, and will be addressed for the final release. (Examples of this include excessive memory allocation and initialization of libraries and resources during launch.). However, the way your application does things (look for resources, traverse the file system, etc) might also be causing some additional problems that might be easy to pinpoint and remedy. You can use Sampler, MallocDebug, or other tools to check for problems.
Services
Services, which were mostly broken in DP1, now work.
GraphicsContext
NSGraphicsContext now has methods to save/restore the current graphics state on a per-thread basis.
ClipView and ScrollView
NSClipView and NSScrollView both support the ability to provide a see-through background (as in the standard about box) via the new setDrawsBackground: method.
Pasteboard
The format for property lists on the pasteboard has changed again; this might break code which makes assumptions about this format. For instance, code which reads an NSString from the pasteboard using dataForType: and attempts to deserialize it by hand is now broken. See DP1 notes (below) for more details.
Copy/paste of plain text now works between the different stacks (Cocoa, Carbon, and Classic). Other types will be added for the final release.
Window Ordering and Activation
NSWindow no longer activates the main window when the key window closes if the main window is not at the top of the app's window z-order. The next window in the z-order which is willing to be key is activated. Most people should not notice any difference.
In addition, a number of window ordering and application activation bugs have been fixed. For one, dragging an item from an application window will no longer bring the application forward. The document drag button has also been fixed so selecting it does not bring its window forward.
However, some activation issues still remain. For instance, when windows are brought up in an application that is not key, they usually come up behind the other windows in the app.
StatusBar
Status bar items with menus that have submenus now work correctly (ie the submenus will appear and track properly).
Sound
In DP2, NSSound can now play uncompressed AIFF sound files as well as uncompressed sounds in NeXT/AU and WAV formats.
In Mac OS X Server, NSSound used to be able to play compressed NeXT-style sound files; these are no longer supported.
Text
NSTextView was caching typing attributes from the previous backing store when it got hooked up to a new backing store. This has been fixed.
NSTextStorage now has the ability to fix attributes lazily; three new methods have been added to support this feature.
The method fixesAttributesLazily should be overridden in concrete subclasses which can do this to return YES. In the abstract NSTextStorage superclass this method returns NO; but the default concrete NSTextStorage subclass returns YES.
processEditing now calls invalidateAttributesInRange:. If the text storage is not lazy this just calls fixAttributesInRange:, causing things to happen as before. If the text storage is lazy this instead just records the range needing fixing.
ensureAttributesAreFixedInRange: should be called in a text storage which is lazy to ensure the attributes are fixed in a certain range. NSTextStorage subclasses that wish to support laziness must call it from all attribute accessors that they implement. The default concrete subclass of NSTextStorage calls this from its accessors to ensure clients always see a consistent view of the attributes.
RTF
NSRTFReader now supports MacOS encoding values for \fcharsetN. It can now read any encoding supported in RTF1.5. Tested against AppleWorks, Word97 on NT, Word98 on MacOS, WordPad on NT, MacOS X Server, and OPENSTEP 4.2 generated RTF files containing Latin1 & Japanese chars. Also, the RTF reader now supports the RTF1.5 Unicode string directives \uN and \ucN.
NSRTFWriter now uses very similar encoding scheme to Word9x. It encodes in font encoding, that provides maximum compatibility with other RTF readers. As the result, it encodes latin1 characters in MacOSRoman on MacOS and WindowsLatin1 on Windows.
This change makes RTF files generated on MacOS incompatible with OPENSTEP 4.x where non-ASCII characters are involved since there was no MacOSRoman decoder on the OS. You can force the reader to generate in Microsoft encodings by setting NSRTFWriteOpenStepCompatibleEncodings default value to YES.
With NSRTFWriteOpenStepCompatibleEncodings == NO (default), generated files with Latin 1 characters were successfully loaded into Apple Works, Word97 on NT, Word98 on MacOS, and TextEdit on MacOS X Server. Unfortunately RTF files with Japanese do not load correctly in TextEdit on MacOS X Server, which did not recognize the Japanese charset indicator.
With NSRTFWriteOpenStepCompatibleEncodings == YES, the generated files were successfully read by TextEdit on MacOS X Server, WordPad on NT, and TextEdit on OPENSTEP 4.2, in addition to the above.
Dragging
Cocoa, Carbon, and Classic are all moving towards a common layer for dragging, and in DP2 dragging a single file between Cocoa and Carbon works. However, there are still some bugs.
Dragging to and from a local pasteboard does not work. The NSDraggingInfo protocol method -draggingPasteboard will always return the pasteboard named NSDragPboard, so the destination will not find an alternate pasteboard used by the source.
The NSDraggingInfo protocol method draggedImageLocation will reflect the offset of the image from the current mouse location only if the source and destination of the drag are the same application. If the drag is from one application to another, draggedImageLocation will return the current mouse location, ignoring any image offset.
The mouse pointer image doesn't change to provide feedback during a drag.
Aborting a modal session
In order to stop a modal session from an NSTimer or delayed performer, you must call -[NSApplication abortModal]. -[NSApplication abortModal] now sends an NSAppKitDefined event to the application rather than raising an NSException, and it will return to the caller.
MovieView
NSMovieView does not work in DP2; the view will be instantiated but no movie will be visible and none will play. This will be fixed as soon as QuickTime is fully available on the system.
ScrollView
Holding down the up/down buttons on a scroller causes the scrolling speed to increase over time by increasing the number of lines that are scrolled at a time. This should not cause any incompatibilities.
By default scroller buttons are now separate; you can set the NSScrollerHasSeparateArrows default to NO if you want your arrows together.
Printing & View Print API
Printing support in AppKit has gone through massive changes. The printing machinery is now hooked into the Tioga print manager; NSPrintPanel and NSPageLayout use Carbon implementations provided by Tioga; and NSView's print related API is simplified because that the original design was aiming to support Adobe's Document Structuring Convention.
NSView now has PDF generation capability via the following methods, which work just as their EPS counterparts:
- (void)writePDFInsideRect:(NSRect)rect toPasteboard:(NSPasteboard *)pb;
- (NSData *)dataWithPDFInsideRect:(NSRect)rect;
Instead of multiple entry points that had been required to support Adobe DSC, NSView now receives only the following five messages during print operation:
- (NSString *)printJobTitle;
- (void)beginDocument;
- (void)endDocument;
- (void)beginPageInRect:(NSRect)r atPlacement:(NSPoint)loc;
- (void)endPage;
Because NSPrintPanel and NSPageLayout use Carbon panels, all the instance variables declared for the classes are never initialized and applications should not access any of the variables.
StringDrawing
drawInRect: variants of NSStringDrawing API now correctly provide clipping, and the drawing appears at the right place regardless of flipped-ness of the focused view.
Box, ScrollView, and ClipView
Sending removeFromSuperview message to the content/document view of NSBox, NSScrollView, and NSClipView will correctly clear their corresponding ivars.
NSBox *myBox;
NSBox *srcBox1;
NSBox *srcBox2;
[myBox setContentView:myViewIsInBox1 ? [srcBox1 contentView] : [srcBox2 contentView]];
The above example worked since srcBox1 and srcBox2 always had the pointer to their content views untouched by -removeFromSuperview method called by the invocation of -setContentView: with myBox. Now, -contentView method returns nil for the second time the above code was executed since content view pointers in both srcBox are cleared by —setContentView:.
Menu
After Preview Release 2, the implementation of NSMenu and NSMenuItem will change to sit on top of the Carbon Menu Manager similar to the Windows implementation of Cocoa menus. This means you should not assume that there is an NSMenuView or NSMenuItemCell behind an NSMenu or NSMenuItem respectively. Images set using -[NSMenuItem setOnStateImage], -[NSMenuItem setOffStateImage], and -[NSMenuItem setMixedStateImage] will still be supported as will setting the font for popup menu buttons.
Fonts
Cocoa and Carbon do not currently use the same set of fonts as CoreGraphics and QuickDraw do not yet use the same underlying library for text rendering. This will be remedied soon.
Please refer to DP1 notes for Font (below) to get new fonts to appear in Cocoa applications for testing purposes.
Removed Defaults
Some defaults that are no longer necessary were removed, along with support for registering them in the default domain:
The AppKit includes the following new features and changes since MacOS X Server. In some cases the notes below might be invalidated by changes in MacOS X Developer Preview 2, listed above. Also note that for notes pertaining to DP1 and earlier, we use the term "Yellow Box" to refer to Cocoa.
Graphics
MacOS X does not include Display PostScript; instead, graphics functionality for Yellow applications is provided through a new client-side framework named CoreGraphics.
One implication of this is that PostScript functions, and code generated using pswrap will no longer work. In the Developer Preview Release, some PSxxx() functions are still supported for binary compatibility, but their use in new code is highly discouraged since their functionality may not be exactly emulated on top of CoreGraphics and they will be removed in a future release. Instead use NSBezierPath or various other drawing classes in AppKit, or functions declared in NSGraphics.h, or CoreGraphics API directly.
The following functions have been added to NSGraphics.h. They should be used in place of PScompositerect():
void NSRectFillUsingOperation(NSRect aRect, NSCompositingOperation op);
void NSRectFillListUsingOperation(const NSRect *rects, int count,
NSCompositingOperation op);void NSRectFillListWithColorsUsingOperation(const NSRect *rects,
NSColor **colors, int num, NSCompositingOperation op);They are equivalent to the non-NSCompositingOperation versions except that they set the compositing operation before filling the rectangles. All compositing modes except NSCompositeHighlight are supported.
The following functions are currently no-ops:
NSDottedFrameRect
The following functions should no longer be used and may return dummy values:
NSHighlightRect , NSCopyBitmapFromGState, NSGetWindowServerMemory
The compositing mode NSCompositeHighlight is no longer supported for any function. Using it for a drawing operation will result in the use of NSCompositeSourceOver instead.
CoreGraphics currently does all drawing in an anti-aliased mode. This has some impact; for instance, code which "erases" drawing by redrawing using a different color might no longer erase every pixel. Images displayed at non-integral boundaries might end up being anti-aliased.
Text is also anti-aliased above a certain point size (currently 16pt). In the Developer Preview release, this value can be tweaked with a user default (see Font discussion below).
Zero-width lines currently do not draw anything. In PostScript this used to draw the thinnest possible line for the device.
Finally, the "-NSHost" command-line option is no longer supported.
DPSContext
Before MacOS X, there was a NSDPSContext object that wrapped a DPSContext handle which, in turn, represented both the application's connection to WindowServer and the graphics context. An NSDPSContext object was instantiated by the framework automatically at application launch time, and you only had to deal with the instance except in certain situations (i.e. your application was multi threaded, or explicitly dealing with a print operation). The "current" NSDPSContext was pretty predictable since the instance that was created at launch time was always current and active, unless your app was in the middle of printing. That is not true in MacOS X, for one thing, NSDPSContext has been removed. (Unfortunately the header files were still left in the release, but they should not be imported. They are not imported automatically by AppKit.h anymore.)
AppKit now only exposes an abstract superclass NSGraphicsContext that is automatically instantiated for each NSWindow. Also, NSWindow instantiates additional NSGraphicsContext objects for each drawing secondary threads as needed. NSView's lockFocus method sets its window's graphics context current, in addition to setting the current coordinate system and clipping state.
Most operations on NSDPSContext are now either not necessary or should be performed on NSGraphicsContext.
For the most part, the principle of implementing the drawRect: method is still the same. By the time your custom NSView class receives drawRect:, the framework has already set up the drawing context for you. You only need to call your drawing functions in the method, and the framework makes sure your drawing appears in the desired view. You can either use AppKit's own drawing API (NSBezierPath, NSImage, and NSString's drawing methods) or call CoreGraphics functions directly. You can query the CGSContextRef handle for the current graphics context by [[NSGraphicsContext currentContext] graphicsPort]. Your drawRect: method would like:
- (void)drawRect:(NSRect)rect { CGSContextRef cgContext = [[NSGraphicsContext currentContext] graphicsPort]; // Construct path (line from 10.0/10.0 to 100.0/100.0 CGMoveTo(cgContext, 10.0, 10.0); CGLineTo(cgContext, 100.0, 100.0); // Set stroke color to white CGSetGrayStrokeColor (cgContext, 1.0, 1.0); // Stroke CGStroke (cgContext);} As you have seen so far, the basic drawing principle remains the same. The lockFocus/unlockFocus method pair sets up the drawing environment, and you call drawing functions. But, the underlying meaning of the current graphics context is changed. The difference is entirely contained in the lockFocus method. The lockFocus method now performs the following operations:
1) Calls +[NSGraphicsContext setCurrentContext:] with the context for the view's window. It creates a new context for subthreads if they don't have one yet.
2) Saves current graphics state by calling -[NSGraphicsContext saveGraphicsState]. Note that PSgstate used to save the current window device, but the saveGraphicsState method does not, since each NSGraphicsContext object has no knowledge of contexts for other windows.
3) Sets up the coordinate system and clipping state by calling CoreGraphics functions.
Note that while it used to work, generally, to call currentContext or saveGraphicsState outside of a focused situation, this is no longer necessarily the case.
Image
Several bugs with GIF and JPEG handling have been fixed.
8-bit indexed TIFFs do not work in this release; you will need to convert them to RGB before using them.
Font
PostScript fonts are not supported in the Developer Preview, and API specific to them is no longer available (details below). The only font file format currently supported is the ".TTF" file.
Formerly, fonts were found in /System/Library/Fonts and other locations. These locations are not searched in this release. Family and face information relevant to the NSFontPanel is still stored in /System/Library/Fonts/.default.fcache, but the directory is otherwise empty.
End-user fonts and application-installed fonts are not supported in this release. The CoreGraphics framework looks for TrueType fonts only in one location, /System/Library/Frameworks/CoreGraphics.frameworks/Resources.
Developers should not use this location for fonts unless absolutely necessary for software development. In future releases, other locations for third-party fonts will be supported.
If it is necessary to install new fonts for development purposes, they should be put in the Resources directory indicated above. If difficulties are encountered after re-login, then (as root) the developer may run the following commands, which assure that the font panel information is updated:
rm /System/Library/Fonts/.default.fcache /usr/bin/fcache /usr/bin/cacheCoveredChars -a After verifying that a new ".default.fcache" has been created, logout and login again for the font panel to be updated. This situation is expected to be temporary as the font storage and discovery mechanisms are being revamped.
Formerly, font metric data was shared among processes and vended by the Pasteboard Server (pbs). In the current implementation, this data is no longer shared, but the information is produced on demand and a copy is kept in each application as needed. This situation will be remedied in the future, since it will be necessary to have shared data again for large font support (e.g., glyph bounding rectangles in Chinese fonts).
The NSText system uses the bounding rectangle of fonts to determine the default line height. In the future, this is likely to change. One effect of using the bounding rectangle is that in this release, all of the line heights have potentially changed from what they were when rendered with PostScript fonts. This affects some NIB files that use fixed-height multi-line text fields: lines near the bottom of the field may be partially clipped. The line heights in the current set of system fonts are sometimes slightly taller than in the PostScript fonts with the same names, due to the fonts' differing glyph complements. The difference is particularly noticeable with the Helvetica family. Developers may wish to check their NIB files for fixed-height multi-line text fields and re-size them with the new fonts if appropriate.
NSFont has been changed from a concrete class into a semi-abstract class. Its instance variables have been completely changed (and were private in previous releases), and its internal structures have also changed. These changes are relatively invisible and should not affect developers (unless they were accessing the internal structures).
The method afmDictionary is being made obsolete. In this release, it returns nil.
The method afmFileContents is obsolete and no longer implemented.
The obsolete widths method is no longer implemented. Formerly, this method returned an array of 256 floats and was only useful with "base" fonts. It has been deprecated for several years.
The method fontWithName:matrix:, while still supported, does not work in exactly the same manner as in the past. The usage of font and text matrices in CoreGraphics is slightly different from what it was with PostScript. In particular, of the two translation coordinates in the NSFont matrix, only Y is actually effective. Developers should avoid using this method, and instead use fontWithName:size: where possible. In this release, there is also a recently-discovered bug that causes all fonts created via fontWithName:matrix: to have an incorrect size. (The size is erroneously multiplied by itself internally during initialization; this can be worked around by supplying a smaller size, and is intended to be fixed in subsequent releases.)
The method isBaseFont always returns YES for TrueType fonts.
A font's capHeight and xHeight are heuristically determined in the current implementation, since these values are not universally provided by the TrueType fonts.
Currently, the only font encoding supported is the NextStepEncoding. That is, only glyphs available in that encoding are reported by instances of NSFont, whether or not the font contains other glyphs. All font instances likewise report that their encoding is NextStepEncoding. This is a limitation that will be removed in the future.
The NSFont method glyphWithName: is not currently implemented in CoreGraphics, and will not return correct results.
The method boundingRectForGlyph: has a bug where it will crash.
Kerning tables are not currently supported by CoreGraphics; hence kerning information is not available via NSFont methods in this release. (I.e., all fonts appear to have no kerning.)
The only glyph packing actually supported in the system is NSNativeShortGlyphPacking. All fonts are presumed to have encoding vectors representable as an unsigned short int. The NSText system only uses NSNativeShortGlyphPacking. The conversion function NSConvertGlyphsToPackedGlyphs() may still be used to obtain other packings; but they are no longer useful with any text system components.
The older PostScript notions of font encoding variability and configurability are being phased out. Developers should avoid using the methods mostCompatibleStringEncoding and encodingScheme. Instead, when it is necessary to determine whether a given glyph is available,developers can use the method glyphIsEncoded:. In addition to providing better international support for complex script rendering, it is intended in the future to make the "Unicode CMAP" accessible via NSFont API, and to utilize each font's glyph IDs directly.
The method widthOfString: is deprecated and should not be used; it is provided for backward compatibility only. This method is only applicable in the case where all characters in a string are known to be renderable with the receiving font in a one-to-one correspondence between characters and glyphs. In all other cases, it is almost guaranteed to not reflect what will actually happen when a string is rendered through the text system. Furthermore, characters of the string which cannot be rendered, as determined when this method is called, are ignored in the width calculation.
Use of a font's bounding rectangle for determining default line height is being phased out in favor of more typographically correct notions using a font's ascent, descent, and "line gap". Developers should use the new method defaultLineHeightForFont when they need to know how tall they should set lines. In the current implementation of the text system, this may not be consistently applied.
The programs buildafmdir and cacheAFMData are obsolete and no longer shipped. These were formerly used for building the font cache formats used by older NextStep systems prior to OpenStep Version 4.0. They have not been used on recent systems, but were kept for compatibility in networks combining machines with old and new operating systems. Their product files, .fontdirectory and .fontlist, (in each font library directory) are likewise obsolete. These files are only used by machines running earlier operating systems than OpenStep Version 4.0.
The replacement program is fcache for caching data used by the font panel. On this release, fcache is only effective when executed by the administrator (root) and only stores information for fonts in the location described above.
The programs prebuild and screenafm are likewise obsolete. There are no replacements. (These programs were formerly used to process hand-tuned bitmaps in PostScript fonts.)
The size of the NSFont class instances have changed, which could generate some binary compatibility problems for subclassers. However, given that NSFont is rarely subclassed, this should not be a problem in general.
As mentioned above, the CoreGraphics framework does anti-aliased drawing. Because anti-aliased fonts tend to have less crisp edges and may cause problems with on-screen readability at small sizes, the AppKit's NSFont implementation by default will use anti-aliased fonts only at 16points and larger. In this release, that size may be controlled through the user default NSMaxScreenFontSize. To globally decrease the size at which anti-aliased fonts are used font above 12 points, for example, a user may execute the following command line:
defaults write NSGlobalDomain NSMaxScreenFontSize
12.0
That tells NSFont to use anti-aliased fonts above 12.0 points globally, and to use screen-fonts up to and including 12.0 points. As with any other default, this may be restricted to a particular application by substituting the application domain, and applications may set or register the value internally via NSUserDefaults.
FontPanel
The font panel formerly updated its text-preview area with the name and size of the currently selected font. This was sometimes problematic and unreliable. The font panel now displays the face name and size in a heading field above the Family/Face browser, leaving the text-preview field available strictly for sample text. The field may be re-sized to zero height if sample text is not desired.
As before, the font panel attempts to render the sample text in the currently selected font (if a single font is selected). If the font is unable to render the sample text because appropriate glyphs are unavailable, another font may be chosen automatically. The mechanism that formerly attempted to choose appropriate sample text is expected to be replaced in a future release.
BezierPath
The following glyph rendering functions in NSBezierPath are not functional in the Developer Preview release:
- (void)appendBezierPathWithGlyph:(NSGlyph)glyph inFont:(NSFont *)font;
- (void)appendBezierPathWithGlyphs:(NSGlyph *)glyphs count:(int)count inFont:(NSFont *)font;
- (void)appendBezierPathWithPackedGlyphs:(const char *)packedGlyphs;
CStringText
NSCStringText, which was obsoleted in MacOS X Server developer releases, has been removed from the system. You should be using NSTextView instead.
If you unarchive nib files which contain NSCStringText instances, you will get a warning and the instance will be converted into a NSTextView, preserving the attributes that are settable through Interface Builder's inspector. Note that there might still be problems using that nib file, if you send that instance methods only NSCStringText understands. You should replace the NSCStringText with a NSTextView in Interface Builder.
Sound
Sound playback in NSSound objects has been disabled for this release.
Preferences
User defaults (as saved by NSUserDefaults and CFPreferences) are now stored in the Library/Preferences directory in the user's home folder, in XML files. One side-effect of this change is that MacOS X Server preferences are distinct from MacOS X preferences. The first time you log in to MacOS X, the MacOS X preferences will be created automatically for you from your MacOS X Server preferences. (This might take up to a minute.)
Remote Launching
You cannot launch an AppKit application from a remote login session because it will fail to connect to the Pasteboard Server due to security constraints. Workaround: from the remote login session, you can first launch a remote instance of the Pasteboard Server in the background with:
/System/Library/CoreServices/pbs -a &
Applications subsequently launched from this session will connect to this Pasteboard Server. Note however that it will not be possible to copy and paste or drag between applications launched this way and other applications launched locally on the target system.
Scripting
AppleScript support is not functional in this release.
Document
NSWindowController now has a public method called synchronizeWindowTitleWithDocumentName which is called whenever the NSDocument has changed in such a way that the window title needs updating. Subclasses can override this if they want to change the way the window title is constructed.
Opening a document of a type that your NSDocument subclass supports for reading but not writing will now result in an untitled document, since the document will not be able to be saved back the way it was loaded.
Reverting a clean document will still perform the revert, but will no longer confirm the revert with an alert panel.
There is a new initWithNibPath:owner: method on NSWIndowController that allows you to specify the full path to the nib file instead of just the name. This is useful when the nib is in a non-standard location (ie in the same bundle as the class that is loading it).
NSWindowController now has a setWindow: method that can be used to set (or unset) the window managed by the controller. Setting the window to nil will not cause the nib to be reloaded next time someone asks for the window.
Text
Fixed a NSLayoutManager bug that could cause display of lines from a different text container in multi-container text setups where lines overlap.
Fixed a NSLayoutManager bug which caused containers with holes to have various display glitches.
Paging up in a non-editable text view will no longer page down.
One new method has been added to the NSSimpleHorizontalTypesetter class for the convenience of subclassers:
- (void)willSetLineFragmentRect:(NSRect *)aRect forGlyphRange:(NSRange)aRange usedRect:(NSRect *)bRectIf implemented by subclasses, this is called within the method layoutGlyphsInHorizontalLineFragment:baseline: after laying out each line fragment, and immediately before calling setLineFragmentRect:forGlyphRange:usedRect: in the NSLayoutManager to record the used line fragment rectangles. This is intended for subclasses to be able to affect e.g., linespacing globally. The "used" rect is expected to be smaller than or equal to the "aRect".
PopUp, Menu
Fixed a menu bug affecting the precedence of key equivalents between service items and regular items when two items want the same key equivalent.
Fixed some problems with popup drawing where the title was either cut off too soon or it ended up overlapping the popup arrows.
Popups now draw the dotted line key view indicator when they are first responder on Windows.
Pasteboard
The serialization format used for putting property lists on the pasteboard now uses XML. Clients of NSPasteboard that used setStringForType: and setPropertyListForType: are unaffected by this change. Clients that assumed the data format was that used by NSSerializer and used setDataForType: should convert to the above methods wherever strings or property lists are the content of the pasteboard. The serialization format used by the pasteboard is subject to further change. To be insulated from future changes, use -setStringForType: and setPropertyListForType: wherever strings or property lists are the content of the pasteboard.
Copy and paste between all applications (Yellow Box, Carbon, and Blue Box) is expected to work using the existing NSPasteboard and Scrap and interfaces. It does not work in this release. Type conversion between traditional OpenStep and MacOS types is expected to be present in a future release.
Dragging
There is no user-visible feedback (cursor change) resulting from setting the drag operation in response to NSDragging protocol methods sent to the dragging destination. Dragging between Carbon and Yellow applications is also not working in this release.
Services
Services for most applications are not available in the services menu in this update, as make_services fails to look in the directories where applications live. Workaround is to execute make_services by hand; in a shell window, do:
make_services /System/Applications /System/Demos /System/Developer/Applications
MovieView
NSMovieView is not yet functional as QuickTime is not available in the Developer Preview release.
Header Imports
A few of the AppKit headers now import Foundation headers more minimally (that is, instead of Foundation.h, one or two specific files might be imported). Depending on what your source code imports and what it was getting defined for it implicitly, you might get warnings or errors duing compile. Fix is to add imports of the correct Foundation headers, or simply import AppKit.h or Foundation.h.
This will not be a problem if your source is importing AppKit.h.
Window Manipulation
Due to changes in the graphics and window management subsystems, some bugs have been introduced in window manipulations:
Dragging an item from an application window will bring the application forward, perhaps obscuring the destination window. For example, dragging an icon from the desktop will bring most recently key Viewer window forward. Workaround is to move the key window of the owning app out of the way of your destination window before initiating a drag.
Windows may be ordered forward incorrectly. If you have two windows open in a given application and one of those windows is key, that same window will come forward the next time you activate the application, regardless of which window you click on to initiate the activation. Workaround is to click on the desired window to bring it forward after activation.
The AppKit includes the following new features and changes between Developer Release 2 and MacOS X Server 1.0. Note that in some cases the notes below might be invalidated by changes in MacOS X Developer Preview 1 and 2, listed above.
Scripting
Mac OS X Server introduces support for scriptable Yellow applications. The support is still considered beta-quality, and is provided for developers to get started making their applications scriptable. See the scripting release note and the documentation for more details. TextEdit and both the Java and Objective-C version of Sketch support scripting and can be used as examples of how to implement scripting in a Yellow application.
ActiveX (Windows only)
Yellow frameworks now have support for ActiveX when running on Windows. See the ActiveX release note for more details. The WebBrowser example shows how to use ActiveX embedding.
Sound
A new class, NSSound, has been added to the AppKit. This class offers simple cross-platform sound-playing capabilities to applications. Editing and recording of sounds is not supported, nor is manipulation of sound parameters (volume, left/right gain, etc.). The sound formats that are understood are the a-law, u-law, 8- and 16-bit signed and unsigned linear encodings of the Microsoft WAV and NeXT/Sun SND (AU) formats. These formats are understood on either platform.
The NSButton and NSButtonCell classes have setSound: methods that can be used to associate a sound with a button.
MovieView
The AppKit now includes an NSMovieView that can be used to play QuickTime movies. It contains sufficient functionality to create an application such as MoviePlayer but does not give full access to all of the QuickTime APIs for content creation. The movie is always resized to fill the whole view and the view can be embedded in another view with appropriate clipping. Note that loading a movie view takes a few seconds when first starting to load the QuickTime libraries. There is an outstanding bug which causes the application to crash if the view is resized to zero width or height.
Binary compatibility on Windows
Due to a bug fix in the Objective-C runtime, binaries from DR2 and previously will not run on Yellow Box for Windows 1.0. These applications should be fully recompiled.
ColorSync support in NSBitmapImageRep
The property dictionary in NSBitmapImageRep has a key declared in NSBitmapImageRep.h as NSImageColorSyncProfileData. The value for this key is an ICC profile.
In 1.0, ColorSync correction of images during display is supported on all architectures. Prior to 1.0 it was only supported on ppc.
Also, when the bitmap image rep is turned into a TIFF representation, the ICC profile is written into the tiff representation. Prior to 1.0, profiles embedded in tiff representations were only supported during reading.
If an NSImage replaces an NSBitmapImageRep by an NSCachedImageRep, the color sync profile is consumed and no longer part of the property dictionary. The values of the pixels in the cached image rep are the ColorSync corrected ones.
Apple Menu items
You may want installation of your application to result in additional items appearing in each user's Apple Menu. To do this, you need to install a bundle in the library search path. For example, if your application was being installed in /Local/Applications, you would add a bundle to /Local/Library/AppleMenu.
The bundle must have the extension .appleMenuItems. Inside the bundle there should be a file AppleMenuItems.plist. If the bundle is localized, there would be a file, AppleMenuItems.strings, in each .lproj for which it is localized. Only the user-visible title of the item needs to be localized.
The format for the plist is not explicitly documented. There is however a substantial example inside the AppKit at /System/Library/Frameworks/AppKit.framework/Resources/English.lproj/AppleMenuItems.plist and /System/Library/Frameworks/AppKit.framework/Resources/English.lproj/AppleMenuItems.strings.
Currently all Apple Menu items found via these search paths are collected and localized once per login. The items become the backdrop against which users make their individual customizations. A user with no customizations sees all the items.
TextAttachmentCell Protocol
In order to give attachments more information about the environment they are being asked to draw in, the NSTextAttachmentCell protocol has been extended. The following methods have been added to the protocol:
- (void)drawWithFrame:(NSRect)cellFrame inView:(NSView *)controlView characterIndex:(unsigned)charIndex;- (BOOL)trackMouse:(NSEvent *)theEvent inRect:(NSRect)cellFrame ofView:(NSView *)controlView atCharacterIndex:(unsigned)charIndex untilMouseUp:(BOOL)flag;- (NSRect)cellFrameForTextContainer:(NSTextContainer *)textContainer proposedLineFragment:(NSRect)lineFrag glyphPosition:(NSPoint)position characterIndex:(unsigned)charIndex;
Effects on existing conformers to the NSTextAttachmentCell Protocol
Existing applications and object files are binary-compatible and do not require recompilation. However, under certain circumstances, you will need to make source changes to recompile existing conformers to the NSTextAttachmentCell protocol. Subclasses of the class NSTextAttachmentCell do not need to be changed; that class implements the new methods by calling the older -cellSize, -cellBaselineOffset, -drawWithFrame:inView:, and -trackMouse:inRect:ofView:untilMouseUp: methods. However, other classes which conform to this protocol will have to be modified in order to recompile. The simplest change is to simply remove the protocol from the class (i.e. remove "<NSTextAttachmentCell>" from the @interface line for your class); this will produce warnings when you recompile, but the resulting application or framework will work as expected. A more complete fix is to implement the new methods to call the old ones, exactly as the class NSTextAttachmentCell does. The most straightforward implementation appears below:
- (NSRect)cellFrameForTextContainer:(NSTextContainer *)textContainer proposedLineFragment:(NSRect)lineFrag glyphPosition:(NSPoint)position characterIndex:(unsigned)charIndex { NSRect result; result.origin = [self cellBaselineOffset]; result.size = [self cellSize]; return result;}- (BOOL)trackMouse:(NSEvent *)theEvent inRect:(NSRect)cellFrame ofView:(NSView *)controlView atCharacterIndex:(unsigned)charIndex untilMouseUp:(BOOL)flag { return [self trackMouse:theEvent inRect:cellFrame ofView:controlView untilMouseUp:flag];}- (void)drawWithFrame:(NSRect)cellFrame inView:(NSView *)controlView characterIndex:(unsigned)charIndex { [self drawWithFrame:cellFrame inView:controlView];}
New conformers to the protocol
When writing a new class that conforms to the NSTextAttachmentCell protocol, first decide whether you need the added information in the new, richer methods. If not, simply implement these methods to call the older, simpler methods, as shown above. If you want to take advantage of the richer methods, however, you should implement the richer methods, then override the older methods to call the richer ones, passing dummy arguments. For instance, if you want to use the text container and line fragment information when sizing your attachment, implement -cellFrameForTextContainer:proposedLineFragment:glyphPosition:characterIndex: to properly calculate the size and location of your cell. Then implement the older methods -cellSize and -cellBaselineOffset to call this method, passing dummy arguments (your -cellFrameForTextContainer:.... method should be tolerant of this case, and fall back to some simple sizing algorithm). This gives you:
- (NSRect)cellFrameForTextContainer:(NSTextContainer *)textContainer proposedLineFragment:(NSRect)lineFrag glyphPosition:(NSPoint)position characterIndex:(unsigned)charIndex { NSRect result; if (!textContainer) { // Do some simple size calculation here ... } else { // Do your full size calculation here ... } return result;}- (NSPoint)cellBaselineOffset { return [self cellFrameForTextContainer:nil proposedLineFragment:NSZeroRect glyphPosition:NSZeroPoint characterIndex:NSNotFound].origin;}- (NSSize)cellSize { return [self cellFrameForTextContainer:nil proposedLineFragment:NSZeroRect glyphPosition:NSZeroPoint characterIndex:NSNotFound].size;}The AppKit text system will never call the older methods; however, other classes that check for the protocol might, so you should make sure to implement the complete set.
In addition to the above changes, the following methods were added to NSLayoutManager to allow this to work:
- (void)setAttachmentSize:(NSSize)attachmentSize forGlyphRange:(NSRange)glyphRange;- (NSSize)attachmentSizeForGlyphAtIndex:(unsigned)glyphIndex;- (void)showAttachmentCell:(NSCell *)cell inRect:(NSRect)rect characterIndex:(unsigned)attachmentIndex;
The last one deprecates the following method, which will continue to work in 1.0:
- (void)showAttachmentCell:(NSCell *)cell atPoint:(NSPoint)point;
Using NSURL to load resources
NSURL's API has been enriched to make it possible to load resources from the network and the web, either in the foreground or the background. To load an URL in the foreground, call resourceDataUsingCache:passing YES or NO, depending on whether you wish to use the cache. If you use the cache, NSURL will see if it or an equivalent URL has already been loaded and saved in the cache. If so, it will return the cached resource data. If not, it will start a fresh load of the URL, returning only after the URL's data has been fully loaded. If you do not use the cache, a fresh load will be started regardless. To load an URL in the background, call loadResourceDataNotifyingClient:usingCache:. This method will start the background load, then return immediately. As the resource is loaded, the client will receive messages from the NSURLClient informal protocol (if the client implements them):
@interface NSObject(NSURLClient)- (void)URL:(NSURL *)sender resourceDataDidBecomeAvailable:(NSData *)newBytes;- (void)URLResourceDidFinishLoading:(NSURL *)sender;- (void)URLResourceDidCancelLoading:(NSURL *)sender;- (void)URL:(NSURL *)sender resourceDidFailLoadingWithReason:(NSString *)reason;@endThe client will receive some number (possibly zero) of URL:resourceDataDidBecomeAvailable: messages, followed by exactly one of URLResourceDidFinishLoading:, URLResourceDidCancelLoading:, or URL:resourceDidFailLoadingWithReason:. The client need only implement those methods that it is interested in receiving.
NSURLHandle and its subclasses
An NSURL loads its resource by using a helper object of the class NSURLHandle. NSURLHandle itself is an abstract superclass, which defines the way by which URLs communicate with their handles. Subclasses of NSURLHandle register for a particular scheme (http, ftp, file, etc.), then implement the actual loading mechanism for that scheme. Currently, Foundation only provides subclasses for the file and http schemes.
Each NSURLHandle subclass also defines a number of properties for the scheme it services. For instance, the permissions, type and size of a file are all properties of file URLs (URLs of the form file:///some-path). You can ask an URL for one of its properties by sending it the propertyForKey: message, passing the key for the property you want. HTTP URLs provide their HTTP header data as properties; use the name of the header field you are interested in as the key. File URLs provide their file attributes as properties; use the file attribute strings defined in NSFileManager.h.
Although there are a number of convenience methods available on NSURL for loading resources and querying properties, some applications will find that the functionality exported by NSURL is not sufficient for its needs. For more extensive control, you should get the NSURLHandle from the NSURL, then message the handle directly. You can do that by sending the NSURL the URLHandleUsingCache: message. For further information about NSURLHandle, look at the header file, NSURLHandle.h.
Writing your own NSURLHandle subclass
One thing a framework or application may want to do is add the ability to handle a new scheme. For instance, you may want to add ftp handling, or perhaps your own custom scheme. You can do this by subclassing NSURLHandle. Your subclass will need to override and implement the following methods:
+ (BOOL)canInitWithURL:(NSURL *)anURL;+ (NSURLHandle *)cachedHandleForURL:(NSURL *)anURL- initWithURL:(NSURL *)anURL cached:(BOOL)willCache;- (id)propertyForKey:(NSString *)propertyKey;- (id)propertyForKeyIfAvailable:(NSString *)propertyKey;- (BOOL)writeProperty:(id)propertyValue forKey:(NSString *)propertyKey;- (BOOL)writeData:(NSData *)data;- (NSData *)loadInForeground;- (void)beginLoadInBackground;- (void)endLoadInBackground;Your subclass should implement canInitWithURL: to return YES if it can service the given URL, and NO otherwise. cachedHandleForURL: should look in the cache (maintained by your subclass) for an existing handle that services an URL identical to the one passed. If so, the cached handle should be returned. If not, a new handle should be created for the URL, stored in the cache, then returned. initWithURL:cached: is the designated initializer for NSURLHandle; the second argument specifies whether the handle will be placed in the cache.
propertyForKey: should fetch the value for any properties that your subclass defines, and return nil for any unrecognized properties. propertyForKeyIfAvailable: should return nil unless the property is already readily available.
If your subclass allows writing out properties or data, you should implement writeProperty:forKey: and writeData: to attempt to write out their arguments, then return YES if the write succeeded, and NO otherwise. Otherwise, you should implement them to simply return NO.
The last three methods, loadInForeground, beginLoadInBackground, and endLoadInBackground do the meaty work of your subclass. They are called from resourceData, loadInBackground, and cancelLoadInBackground respectively, after checking the status of the handle. (For instance, resourceData will not call loadInForeground if the handle has already been loaded; it will simply return the existing data.) loadInForeground should synchronously fetch and return the URL's resource data. beginLoadInBackground should start a background load of the data, then return. As the background load progresses, your subclass should message itself with didLoadBytes:loadComplete:, passing the bytes received, and whether the load has finished. If the load fails at any point, your subclass should call backgroundLoadDidFailWithReason:, passing a human-readable string giving the reason for the failure. NSURLHandle implements these methods to inform its clients (including the URL itself) of the new status. Finally, your subclass should override cancelLoadInBackground to stop a background load in progress. Once a handle has received a cancelLoadInBackground message, it must not send any further didLoadBytes:loadComplete: or backgroundLoadDidFailWithReason: messages.
Now all that remains is to inform NSURLHandle of your new subclass; you do this by sending the NSURLHandle class the registerURLHandleClass: message, passing your subclass as the argument. Once this message has been sent, as NSURLHandle is asked to create handles for a given URL, it will in turn ask your subclass if it wants to handle the URL. If your subclass responds YES, NSURLHandle will instantiate your subclass for the URL.
Using NSUndoManager from Java
Because the invocation-based undo registration mechanism is unavailable in Java, the Java API of NSUndoManager has been enriched. The following method has been added to NSUndoManager:
public native void registerUndoWithTargetAndArguments( java.lang.Object target, com.apple.yellow.foundation.NSSelector selector, java.lang.Object arguments[]);This allows the caller to put an arbitrary method invocation on the undo stack. The first argument is the intended receiver for the method, the second argument specifies the method, and the third argument is the array of arguments to be passed.
Note that the arguments array is an array of Objects. When your method takes scalar types, you should use the equivalent Java wrapper classes in the arguments array. For instance a method which takes an int should build a java.lang.Integer instance that contains that int to put into the arguments array. The undo manager will resolve all this by the time it needs to build the invocation to send. See the Java version of the Sketch application's source code for an example of the use of this new method.
There is a known bug which prevents float arguments (registered as java.lang.Float objects) from being properly registered; Methods which take floats will not be able to be undone properly at this time. The argument will always be zero by the time your method is invoked from the undo manager. Sketch has this problem with the setStrokeLineWidth() method in the Graphics class. You can work around this by having your method take a java.lang.Float instead. This bug should be addressed in an upcoming release.
Using Undo with the Text System
A design flaw has been discovered when using undo with the AppKit text system. If you have a text view and have enabled undo with it by calling [myTextView setAllowsUndo:YES], the undo stack managed by the text view will become corrupted if the text storage is manipulated directly. A handful of methods on NSTextView (the methods inherited from NSText of the form -replaceCharactersInRange:....) will also corrupt the undo stack. Once corrupted, calls to undo and redo will have unexpected results, possibly crashing the application. To avoid this, we recommend that you either manipulate the text only through the safe NSTextView methods, manage the undo stack yourself, or disable undo. This bug will be resolved in a forthcoming release.
TableView
Notes on the autosave columns feature:
Column identifiers used with NSTableView's "autosaveTableColumns" feature must conform to the NSCoding protocol. NSTableView will raise an exception if the user attempts to perform the autosave (into User Defaults) on a table column identifier that is not an archivable object. In DR2, the view would allow one to attempt this, and the program would crash mysteriously during User Defaults writing.
The autosave feature is only actually enabled when there is an autosave name set. code should call setAutosaveName: before calling setAutosaveTableColumns:YES. In previous releases, this would autosave any nameless tableview with the same key, "NSTableView Columns *nil*".
The correct way to use this feature for NSTableView instances in NIB files is to set the name and enable it after the NIB file is loaded and before display occurs. The "awakeFromNib" method in a controller class is a good place to do this.
Because of this autosave feature, notifications of column width changing are suspended while a NSTableView is tiling itself or otherwise laying itself out by a user column-resize operation. The columns are saved upon completion of the layout operation. Were the notifications not suspended, the setWidth: calls during layout would cause notifications to be sent and column settings to be saved. This change prevents autosave from happening during layout and resizing operations.
Note: Developers may find that programs which utilized the autosave feature in DR2 can crash or raise an exception when trying to read old defaults under the new regime. (The exception would typically occur in methods called through the private method _readPersistentTableColumns; and the NSLog message will state that NSInlineUnicodeString does not respond to the bytes method.) The crash can be remedied by first removing the old autosave defaults for that application. (Use "defaults delete TheApp TheKey", or when in doubt, "defaults delete TheApp" to remove all of the defaults for the offending application.
Columns are saved by column identifier. In the DR2 release, the column identifier was expected to always be an NSString, though it is properly an "id" type. In this release, the column identifier can be any object that responds to the NSCoding protocol (though typically an NSNumber of an NSString).
Notes on cell editing and data reloading:
When the reloadData method is called, any cell that is in the midst of being edited will lose the editing changes currently in progress. (I.e., a cell that has the blinking cursor at the time of the reload will lose whatever has changed.) This can be remedied by explicitly ending the editing session before the reload, which will preserve the data in the cell. Before sending reloadData to the Table View, send endEditingFor: to the window in which it lives. For example:
[[myTabView window] endEditingFor:self]; [myTabView reloadData];
OutlineView
The delegate method outlineView:willDisplayOutlineCell:forTableColumn:item: was never being sent. This has been fixed so that it is called (if the delegate responds to it) just before the cell is drawn.
The method removeTableColumn: should not be used for the "outline table column", and if an attempt is made to do that (which would result in an inconsistent state), the method will log an error and no change will take place. Use the setOutlineTableColumn: method to properly replace the outline table column if necessary. First, add a new column if you need to, then use setOutlineTableColumn: to switch to the new table column, then remove the old column if desired.
Notes on Support for the "Euro" Currency Sign
Most of the fonts shipped with this release have not been modified to include the new "Euro" currency sign of the European Monetary Union. The Charcoal font, however, has been modified to include this glyph in the encoding position formerly reserved for the International Currency Sign, a seldom-used character. It is expected that in the future if other fonts are modified, they would likewise include the Euro sign at this position. The character encoding for the Euro sign in the Unicode standard is U+20AC, as documented in Unicode Technical Report #8. (The International Currency Sign is encoded at U+00A4.)
To facilitate use of the Euro sign without system modifications, if new fonts containing it are added by users or other vendors, both the character for the Euro sign and for the International Currency Sign are rendered with the glyph encoded at 0x00A8 in the "NextStep" font encoding.
In other words: in the Charcoal font, the glyph for the International Currency Sign is unavailable, having been replaced by the glyph for the Euro sign. In the other fonts, the glyph for the Euro sign is unavailable. However, all NextStep-encoded fonts respond as if the glyph for the Euro sign were encoded at 0x00A8.
To display the proper glyph for the Euro sign in plain text, you may use the Charcoal font. To display the proper glyph in RTF or other fancier formatted documents, you may enter the character U+20AC, select it, and change the font of that one character to Charcoal.
Notes on Keyboard Support for the "Euro" Currency Sign
Most of the keyboard layouts shipped with Mac OS X Server now have the Euro sign attached to the Alt-Shift-4 key combination. If the keyboard layout you have chosen is not configured this way, or if you wish to change the key combination for generating the Euro, you can use Keyboard.app which can be found in /System/Demos.
Because keymaps currently do not support the assignment of actual Unicode characters, thetechnique for assigning the Euro sign to a key is not obvious. To assign the Euro to a key, you should use the 0xa0 encoding slot of the Symbol character set. This encoding slot is unused in the standard Symbol encoding.
To assign this to a key, open your keyboard mapping file in Keyboard.app, select the key you want on the picture of a keyboard and make sure that the checkboxes for any modifiers you want are checked. For example, to assign it to Alt-Shift-4, select the four key and check the Shift and Alternate checkboxes. Then, using the Character Code Palette (available from the Tools menu), select the Symbol encoding from the popup at the bottom of the window and drag the chip for 0xa0 onto the keyboard and drop it on the key that you want to assign. Slot 0xa0 is the 1st column of the 11th row of the Character Code Palette. When you have assigned the Euro sign to the key you want, save the keyboard mapping into your ~/Library/Keyboards directory (creating the Keyboards directory if necessary), and use Preferences.app to select your new keyboard mapping.
Typesetter
NSTypesetter has been made a public class in this release. The class NSTypesetter itself is abstract. The one concrete subclass is NSSimpleHorizontalTypesetter, which is the class used as the default throughout the system. Some instance variables of the concrete class are accessible for use by subclassers.
The following NSLayoutManager methods have been exposed to support use of custom NSTypesetter subclasses:
- (NSTypesetter *)typesetter;- (void)setTypesetter:(NSTypesetter *)typesetter;- (unsigned)getGlyphsInRange:(NSRange)glyphsRange glyphs:(NSGlyph *)glyphBuffer characterIndexes:(unsigned *)charIndexBuffer glyphInscriptions:(NSGlyphInscription *)inscribeBuffer elasticBits:(BOOL *)elasticBuffer
Browser
Some delegate methods of the NSBrowser (notably browser:columnOfTitle:) depend on the option-settings and state of the browser instance at the time the setDelegate: method is called, but the documentation is not clear on this point. It is best to take care of all option settings of the browser instance (such as setTitled: and setTakesTitlesFromPreviousColumn:) before setting the delegate via setDelegate:.
Window
NSWindow now has -isZoomed API to let you ask whether a window is currently zoomed. The answer will be YES if hitting the zoom box or calling the zoom: method would cause the window to restore the last user state. It will be NO if hitting the zoom box would cause the window to zoom.
DocumentController
The Java signatures for the following methods have changed to be more specific. This change will require a recompile of Java applications that use the document architecture.
public static native NSDocumentController sharedDocumentController();public native NSDocument makeUntitledDocumentOfType(java.lang.String);public native NSDocument makeDocumentWithContentsOfFile(java.lang.String, java.lang.String);public native NSDocument makeDocumentWithContentsOfURL(java.net.URL, java.lang.String);public native NSDocument openUntitledDocumentOfType(java.lang.String, boolean);public native NSDocument openDocumentWithContentsOfFile(java.lang.String, boolean);public native NSDocument openDocumentWithContentsOfURL(java.net.URL, boolean);public native NSDocument currentDocument();public native NSDocument documentForWindow(com.apple.yellow.application.NSWindow);public native NSDocument documentForFileName(java.lang.String);
These methods all used to return java.lang.Object in DR2.
WindowController
The Java signatures for the following NSWindowController method has changed to be more specific. This change will require a recompile of Java applications that use the document architecture.
public native NSDocument document();This method used to return java.lang.Object in DR2.
Application
activateIgnoringOtherApps: will now unhide and activate a hidden application if flag is YES. In DR2 and previous releases, this method had no effect on a hidden application.
NXOpen, NXOpenTemp, and NXPrint are no longer recognized as command line options. Any use of these keywords should be replaced by NSOpen, NSOpenTemp, and NSPrint, respectively.
Threading
It is now possible to create a window on a secondary thread.
It is now possible to call [NSApplication postEvent:atStart:] from a secondary thread. This will result in delivery of the event to the event queue on the main thread.
In DR2, multi-threaded applications could hit a race condition where a font defined on one thread was not accessible on another. This has been fixed for drawing fonts. The fix does not apply to printing fonts, but this should not be a problem as it is not expected that an application will be printing from two threads at once.
For additional release notes on threading support please see ThreadSupport.html.
Using NSFileHandle with sockets on Windows
Because read() and write() do not work on sockets on Windows, a file handle created with [[NSFileHandle alloc] initWithNativeHandle:(HANDLE)someSocketHandle] was not usable.
If read() and write() fail, the file handle implementation now tries recv() and send(), respectively, and a file handle created this way is now usable.
You may find it particularly convenient to go through the NSFileHandle API in cases where you do not know whether a handle is a socket or a handle to a regular file system file. For example, a child process whose parent set it up to read or write from a socket using stdin and stdout can successfully read from stdin and stdout using the file handle API, whereas stdio library calls such as getchar() and putchar() will fail.
Dragging on Windows
Due to an incorrect match between messages sent by the OLE drag manager and the NSDraggingDestination informal protocol, draggingEntered: was sent repeatedly and draggingUpdated: was not sent. Developers who have worked around these longstanding problems should remove their workarounds as of this release.
Continuous Completion in NSComboBox and NSComboBoxCell
A new method setCompletes: has been introduced. If completes is YES, after each change to the text of a combo box cell, completedString: is called. If the string returned by completedString: is longer than the existing text, the text is replaced, and the additional material is selected. If the user is deleting text or the selection (or insertion point) is not at the end of the text, completion is not attempted.
An implementation of completedString: is provided. If the combo box (or combo box cell) uses a data source, and the data source responds to comboBox:completedString: (or comboBoxCell:completedString: in the combo box cell case) the return value of this method is used. Otherwise, this implementation just goes linearly through the items until it finds an item which is suitable as the completed string. Subclassers of completedString: do not need to call super. It is ok to return nil (in which case no completion occurs). completedString: is generally not called directly.
ButtonCell
The constants NSMomentaryPushButton and NSMomentaryLight where reversed. If you called [NSButtonCell setButtonType:] with these constants, they would do the wrong thing. For compatability, these constant names have been kept but new ones with the correct naming have been introduced: NSMomentaryLightButton and NSMomentaryPushInButton.
StatusItem
The limit on the width of status bar items has been increased (to 10,000, basically unlimited).
MenuItem
The Windows implementation of NSMenuItem now supports black and white images for use as marks to indicate on, off, or mixed states. If custom images are not set, then the checkmark is used for the on state, the dash is used for the mixed state, and no image is used for the off state. The image will be centered in the bounds of the menu item icon.
ToolTips
In DR2 and previously, tool tips did not work in modal windows. They now do.
Standard About Panel
The following two methods have been added to NSApplication to allow putting up a standard About panel. The first one allows you to specify the various fields. Default values (as described below) are used for fields that are not specified. The second method, intended for target/action usage, simply uses all default values:
- (void)orderFrontStandardAboutPanelWithOptions:(NSDictionary *)optionsDictionary;- (void)orderFrontStandardAboutPanel:(id)sender;
The following are keys that can occur in optionsDictionary:
"Credits": NSAttributedString displayed in the info area of the panel. If not specified, contents obtained from "Credits.rtf" in [NSBundle mainBundle]; if not available, blank.
"ApplicationName": NSString displayed in place of the default app name. If not specified, uses the value of NSHumanReadableShortName in the localized version of Info.plist. If that's not available, uses [[NSProcessInfo processInfo] processName].
"ApplicationIcon": NSImage displayed in place of NSApplicationIcon. If not specified, use [NSImage imageNamed:@"NSApplicationIcon"]; if not available, generic icon.
"Version": NSString containing the build version number of the application ("58.4"); displayed as "(v58.4)". If not specified, obtain from the NSBuildVersion key in infoDictionary; if not specified, leave blank (the "(v)" is not displayed).
"Copyright": NSString containing the copyright string. If not specified, obtain from the value of NSHumanReadableCopyright in the localized version InfoDictionary; if not available, leave blank.
"ApplicationVersion": NSString displayed as the application version ("MacOS X Server", "WebObjects 3.5", "ClarisWorks 5", ...). If not specified, obtain from the NSAppVersion key in Info.plist. If not available, leave blank; then the build version, if provided, is displayed as "Version 58.4".
Attributed Strings in FoundationJava
Note that although the NSAttributedString constructors from AppKit are listed in FoundationJava in the Yellow/Java APIs, these are still implemented in the AppKit and require AppKit to be linked in to be usable.
Text
The text object now supports more sophisticated underlining; you can underline by words, and by strikethrough. You can "or" together NSUnderlineByWordMask and NSUnderlineStrikethroughMask with the base underline style (NSNoUnderlineStyle or NSSingleUnderlineStyle) to get the desired effect.
In DR2 and previously, hyphenation could (especially with high hyphenation factors, above 0.8) cause display glitches (overwritten lines, for instance) in some rare circumstances. This is now fixed.
A leak in the text system that caused the text view and related objects to leak when undo was enabled has been fixed.
SplitView
The following delegate method:
- (void)splitView:(NSSplitView *)sender constrainMinCoordinate:(float *)min maxCoordinate:(float *)max ofSubviewAt:(int)offset;
was deprecated in favor of:
- (float)splitView:(NSSplitView *)sender constrainMinCoordinate:(float)proposedCoord ofSubviewAt:(int)offset;- (float)splitView:(NSSplitView *)sender constrainMaxCoordinate:(float)proposedCoord ofSubviewAt:(int)offset;
In 1.0, the old one will be called if it's still implemented.
View
New method lockFocusIfCanDraw has been introduced. Any thread drawing directly (eg. outside of the standard display mechanism) should use this method to check drawing validity before it starts drawing.
FileWrapper
The string encoding for a serialized directory wrapper is changed from NSNEXTSTEPStringEncoding to NSUTF8StringEncoding. This means non-ASCII characters in serialized RTFD data lose backward compatibility.
Java
The alpha versions of the Java APIs to the Yellow Box have been removed. They were provided in DR2 for compatibility only.
The Application Kit includes these new classes, features, and changes since the first Developer Release. Many of the new features have been documented, so please refer to the documentation for more detail.
Java
The Java APIs to the Yellow Box, which were distributed in their alpha form in the first Developer Release, have undergone some changes and are now considerably more robust and finalized. Please see the Java APIs release note for details.
Document-Based Application Architecture
The new NSDocument, NSDocumentController, and NSWindowController classes ease the task of creating document-based applications. These classes encompass a lot of the behavior that applications commonly implement to deal with documents. Document-based applications that use these classes will be better suited to take automatic advantage of new features added to the Yellow Box.
Instances of NSDocument represent documents. NSDocument is abstract; you subclass it to add storage for the document and behaviors such as reading and writing. An NSDocument appears in the responder chain right after its window's delegate, and the NSDocument is set up to be the first-responder target for various actions such as save, revert, and print. In addition, NSDocument manages its window's edited status and implements much of the behavior required for undo and redo operations.
Each application has one instance of NSDocumentController, which manages the list of documents and implements application-wide behavior.
NSWindowController provides basic nib-file and window management. For simple situations (one document, one window), you will usually have one instance of NSWindowController per document. An NSWindowController can also be used to manage windows in non-document-based applications. Subclassing is optional.
A new project type, "Document Based Application," facilitates the initial setup required to create an application based on these new classes.
To better support the new document object and the Finder (in upcoming releases), some changes were made in the contents of the Info.plist and CustomInfo.plist files found in application wrappers and bundles. See the release note on the Information Property List Format for details.
Undo Support
Enterprise Object Framework's EOUndoManager has been modified and made a new Foundation class, NSUndoManager. This class makes it easier for applications to support undo and redo operations. Clients register callbacks that the undo manager invokes when users request an undo or redo operation. NSUndoManager supports grouping and multiple levels of undo.
NSResponder now provides a method called undoManager; clients should use this
method to get access to an NSUndoManager. The default behavior in NSResponder
is to call the next responder; this usually ends up in NSWindow, which is in
the responder chain. The default behavior of NSWindow is a bit more
complicated; if the window has a window controller with a document, NSWindow
implements this method by first looking to see if its document has an undo
manager and returning it if that is so. Otherwise, NSWindow invokes the new
delegate method undoManagerForWindow:
If the delegate doesn't implement this method NSWindow creates and returns its
own NSUndoManager.
The text system now also supports undo and redo operations.
Although DR2 contains no scripting features, a release note has been provided to provide information to help you design your application so that it will be scriptable when the Yellow Box does provide scriptability. This release note also discusses the document architecture and undo features in some detail.
The ActiveX framework (ActiveX.framework) brings together the first pieces of Yellow Box/ActiveX integration by allowing you to use ActiveX Automation objects in Objective-C. Note that this functionality is currently pre-alpha, meaning the packaging and APIs themselves are subject to change in the next release.
NSDispatchProxy is a concrete subclass of NSProxy that defines proxies for ActiveX Automation objects. When an NSDispatchProxy receives a message, in most cases it forwards the message through DCOM (Distributed Component Object Model) to the real ActiveX Automation object, supplying the return value to the sender of the message if one is forthcoming, and propagating any exception back to the invoker of the method that raised it. See the documentation provided in the framework for more information.
The Application Kit and Foundation now provide more multithread safety, enough
to support AWT's multithreaded drawing demands and allow developers to do a
variety of tasks using multiple threads. Drawing from multiple threads is
supported as long as each thread uses its own connection to the window server;
this is easily accomplished by using the NSApplication factory method detachDrawingThread:toTarget:withObject:.
Status Bar
NSStatusBar and NSStatusBarItem are two new classes that provide a way to add items to a system-wide status area. These status-bar classes replace the use of application tiles as well as providing extended functionality. An application can add status-bar items that are strings, images, tool tips, or menus and can invoke an action in a specified target when users click on a status-bar item.
The same API is available on both Macintosh and Windows. On the Macintosh, the items appear on the right hand side of the menu bar. Under Windows, the status items appear as part of the taskbar notification area (usually right side of taskbar). The custom view feature is not supported under Windows.
Menu and Popup
The Apple menu is now automatically filled with a default list of applications and two special entries that represent the lists of recently used applications and documents. In this release there is no editor with which users can configure the contents of the Apple menu, and both the contents of the list and the storage for the contents is subject to change in the future.
The Application Kit "hack" of changing the first top-level menu to an Apple menu if its title is "Info" still works in this release; however, you should switch your menus to use a real Apple menu.
Any menu that is a part of an application's main menu can be torn off. To tear off a menu start tracking in it as if you were going to choose an item and drag off the bottom of the menu a little distance. The mouse button must be down to tear off a menu. The menus you tear off in an application are remembered and restored as you quit and relaunch the application.
Menus now support keyboard UI: While a menu is tracking you can now use the arrow keys to navigate. Since there is currently no way to start tracking the main menu through the keyboard, this isn't yet very useful for normal menus, but it means that you can use the keyboard to choose items in a popup or pulldown menu. When the focus is on an NSPopUpButton, pressing the space bar pops the menu up. Then you can use the arrow keys to move between items; press the space bar again to choose an item.
Control-click now show the context menu for a view if the view has one. The
Control-click is not seen (as a mouseDown:) by views that have context menus.
Views that do not have context menus still receive mouseDown: for
Control-clicks. However, using Control as a mouse modifier is discouraged, even
if you don't have context menus. Over time, Yellow Box applications provided by
Apple will migrate away from using Control-click for anything but context
menus.
User key-equivalent overrides: This feature is implemented but the UI for setting them is not in this release.
You can now specify the arrow position for bezel style and borderless pop-up menus.
You can now independently set the horizontal and vertical line and page scroll amounts.
NSSplitView has additional delegate methods to allow you to constrain the resizing and collapsing of the view.
The new convenience method selectTabViewItemWithIdentifier: allows you to
select a tab item by its identifier. As with the other methods in NSTabView,
this method raises an exception if the identifier is invalid.
In Developer Release 1 on MacOS platforms, application delegates did not
receive applicationShouldTerminate:
on power-off or logout events in addition to normal application termination.
This now works properly. If the application delegate implements this method and
returns NO, then the logout or power-off is cancelled.
Applications that need to distinguish between a termination associated with
the end of a login session and a termination through a Quit (or Exit) command
could do this by registering for the NSWorkspaceWillPowerOffNotification.
This notification is posted prior to calling applicationShouldTerminate:.
Additional relevant events that occur later in the termination sequence are
the posting of an NSApplicationWillTerminateNotification
and a corresponding message to the application delegate of applicationWillTerminate:,
if it implements the method.
For documents managed by an NSDocumentController, it is not necessary for the application delegate to become involved in the save or cancel process.
Buttons include a new feature makes the border of the button visible only
when the button is enabled and the mouse is over the button. You can enable or
disable this feature by invoking the method setShowsBorderOnlyWhileMouseInside:;
the current setting of this attribute is returned by the method showsBorderOnlyWhileMouseInside.
These two method are available in both NSButton and NSButtonCell and this
setting is archived and restored. When you are dealing with matrices, invoke
the cell methods directly.
You can override the mouseEntered:
and mouseExited:
methods added to NSButtonCell in order to make additional appearance
changes. These methods are invoked when the button cell is enabled, the showsBorderOnlyWhileMouseInside
flag is set to YES, and the mouse enters or exits the button.
The new method colorizeByMappingGray:toColor:blackMapping:whiteMapping:
supports colorization of images. This method primarily maps grayscale user
interface component images to different color schemes.
In this release NSBitmapImageRep has some preliminary support for ColorSync profiles in TIFF files. The profile is loaded and used if possible. It is not retained on save. Also, it works only on the PowerPC architecture.
As mentioned in the Developer Release 1 notes, NSBitmapImageRep now supports JPEG, GIF, and PNG reading and writing. This support is not finalized and will probably change for the first Customer Release to include additional formats using QuickTime codecs.
Because different image formats contain additional information, this
information is stored as NSBitmapImageRep properties. You can set these
properties in the image by using the setProperty:withValue: method and get
the properties with valueForProperty:,
or you can add or override the properties when creating the
representation using representationOfImageRepsInArray:usingType:properties:
and representationUsingType:properties:
methods. The properties are stored in an NSDictionary using an NSString for the
key. The following key/value pairs are currently defined:
NSImageCompressionMethod: --
The TIFF compression method for TIFF files. The enumerated value is stored
in an NSNumber. NSImageCompressionFactor: --
The TIFF and JPEG compression factor. The float value is stored in an
NSNumber. NSImageDitherTransparency: --
Used for GIF output only. It is a boolean value stored in an NSNumber. If
true, transparency is dithered to get an alpha channel effect. NSImageRGBColorTable: --
For GIF input and output. It consists of a 768 byte NSData object that
contains a packed RGB table with each component being 8 bits. NSImageInterlaced: -- For
PNG output; this value indicates that the output image is to be
interlaced. It is a boolean value stored in an NSNumber.]
Several new factory methods support additional system colors:
keyboardFocusIndicatorColor: --
Color to use to draw the keyboard focus ring around text fields and
buttons. headerColor: -- Background
color for header cells in Table/OutlineView. headerTextColor: -- Text
color for header cells in Table/OutlineView MacOS X Server now supports dynamic updating of color schemes; if the user
changes any of the system colors in the Preferences application, applications
will be updated dynamically. If you create or cache any custom colors based on
system colors, you might need to listen to the NSSystemColorsDidChangeNotification
and take appropriate action when the color scheme is updated.
As discussed above, NSBitmapImageRep also provides a method to colorize images; this method might come in handy when you are adopting bitmap images in the user interface to new color schemes.
New C Types
The typedefs NSPointArray,
NSSizeArray, NSRectArray, and NSRangeArray are added to Foundation
and the AppKit to indicate methods and functions that take C-arrays of NSPoint,
NSSize, NSRect, and NSRange.
Similarly, the typedefs NSPointPointer, NSSizePointer, NSRectPointer, and NSRangePointer
are added to indicate methods and functions that return NSPoints, NSSizes,
NSRects, and NSRanges by reference.
These typedefs do not really change the API, but they do clarify the intentions of the few methods taking pointers to structs, making it possible for the Java bridge to convert them correctly.
FontManager
The methods availableFontFamilies,
availableMembersOfFontFamily:,
and localizedNameForFamily:face:
are added to provide more information about font families.
Window
NSScreenSaverWindowLevel
has been added to allow developers to place windows above everything else,
including menus. NSDockWindowLevel
has been deprecated and should not be used.
The Application Kit now supports a utility look for panels. This is
typically used for small nonmodal panels that float and hide when the
application is deactivated, such as a tools palette. A utility window is a
floating panel by default, but you can disable this behavior by invoking setFloatingPanel:
with an argument of NO.
You can create utility windows programmatically with the NSUtilityWindowMask
style (which should be specified in conjunction with NSTitledWindowMask),
or in Interface Builder, by enabling the "utility window" option in
the Panel Attribute inspector.
The "Minimize" attribute, which was changed to windowshade windows in Developer Release 1, now either minimizes or windowshades depending on the user preference.
A known problem in this release is the behavior of windows marked as
"Visible at launch" in Interface Builder. When an application is
launched they become visible but they do not become key even though the
application is active. For a window to become key, makeKeyAndOrderFront:
must be explicitly invoked.
An NSURL class has been added to the Foundation framework. In this release the class only supports file URLs.
Various classes in the Foundation and Application frameworks have new APIs
that take URLs in addition to file names. For instance, NSData's initWithContentsOfFile:
now has a parallel initWithContentsOfURL:.
You can now get back an array of URLs from the open panel in place of the array
of file names. If your application starts using these new APIs, it will inherit
richer behavior (such as accessing files and resources over the network) when
NSURL class is expanded in future releases.
HTML
NSAttributedString's initWithHTML:documentAttributes:
method has been deprecated in favor of initWithHTML:baseURL:documentAttributes:,
which provides a way to supply the appropriate base URL.
Please note that the prefix HTML is reserved and in use by the (currently private) HTML framework.This framework is dynamically loaded when the Application framework needs to parse HTML files; any conflicts in global names could lead to problems at that time.
Image
Invoking NSImage's imageNamed:method
with images that don't exist can be costly, forcing a search of the
application's main bundle and the Application framework. If you wish to detect
such calls to this method, run your application with the NSLogMissingNamedImages
default set to YES (as with all defaults, this can also be specified through
the command line).
The method setKnobThickness:
currently has no effect.
The Foundation framework now contains NSDistributedNotificationCenter, a class for sending notifications between processes on a single machine. In addition to the basic features in NSNotificationCenter, this class provides a way to set a suspension behavior on notifications: You can cause them to be delivered immediately to all applications, or delayed until the applications are not suspended. The Application Kit ensures that applications become suspended when they are deactivated.
Distributed notifications can be expensive if they are sent often and cause the receiving applications to wake up on delivery. For that reason you should use them sparingly and with the suspension behavior generally set to NSNotificationSuspensionBehaviorCoalesce.
BezierPath
There are significant changes in the NSBezierPath APIs, which are not yet documented. Please refer to the header file for the new API.
Compatibility was not maintained between the old and new APIs, so earlier code that used NSBezierPath should be recompiled.
This release introduces some additional input method API. At the core of
interaction, insertText:
and setMarkedText:selectedRange:
can receive an instance of NSAttributedString as their arguments where they
were restricted to NSString in the previous releases. Input servers are
expected to query valid attributes with the validAttributesForMarkedText method.
Currently the following attributes are supported by NSTextView for marked text:
Foreground color (NSForegroundColorAttributeName), background color
(NSBackgroundColorAttributeName), and underline (NSUnderlineAttributeName).
This release provides more sophisticated programmatic interaction between the user and the input methods, including allowing an input method to track mouse events on text.
When Developer Release 2 ships, Apple's Developer Support web site will make available source code for a sample input method that uses the new APIs to implement a hex input method (allowing you to type a hex number to specify any Unicode character).
By invoking setAutosaveTableColumns:
you can get the column configuration (such as ordering and sizes) of a table or
outline view to be saved, per user, under a key specified via setAutosaveName:.
This works much like the frame saving feature in NSWindow. Outline view also
provides an additional method, setAutosaveExpandedItems:, to let applications
save the expansion state of the viewed data. To enable this, you will also have
to respond to the new data-source methods that allow the outline view to
archive the items.
Additional delegate methods and notifications in NSOutlineView allow instances to communicate expansion and collapsing of items.
The printing method knowsPagesFirst:last:
has been deprecated in favor of knowsPageRange:, which is
easier to map to Java. The old method will keep on working but will no longer
be documented.
Invoke setAllowsUndo:with
an argument of YES to enable undo in the text system.
If you write your own connection inspector for IB, you may wish to use the NSNibControlConnector, NSNibOutletConnector, and the NSNibConnector classes. NSNibControlConnector provides a target/action connection between objects in a nib file. NSNibOutletConnector provides an outlet connection between objects in a nib file. NSNibConnector is the common base class; you may wish to subclass it for your own custom connectors between objects.
DataLinks, which were made obsolete between NextStep and OPENSTEP releases, have been removed from the framework.
NSComboBoxCell now provides automatic completion of typing.
The way keyboard UI is started on MacOS X Server has been modified. In windows without editable textfields, hitting Tab will enter you into keyboard UI mode; until that time, keyboard focus will not be on any UI object. In windows with editable textfields, if an initial first responder has not been specified, the textfield will have the focus when the window is brought up. On Windows the situation is as it was; that is, it works like Windows does.
On MacOS X Server, Command-up-arrow and Command-down-arrow used to change the ordering of windows (without making them key). This is no longer the case.
The Escape key (Esc) now no longer does escape completion by default; instead, it cancels the current action (usually dismissing panels). To change Escape back to completion, create or edit the DefaultKeyBinding.dict file in ~/Library/KeyBindings so that it contains this line:
{ "\033" = "complete";}
Consider NSCStringText and all related API (everything in obsoleteNSCStringText.h) to be deprecated. Although this code will keep working for awhile, it is highly recommended that you switch over to the new text system, which provides much more functionality in a much cleaner way. If there are any reasons that prevent you from moving to the new text system, please let us know through Developer Support.
In DR1, the Application Kit includes these new classes, features, and changes since OpenStep 4.2:
NSPICTImageRep
A class for objects that represent PICT images. For the Developer Release, only bitmap PICTs work.
NSProgressIndicator
A class for objects that implement a determinate or indeterminate progress indicator. The indeterminate progress indicator can be animated in a separate thread, allowing its use even in computation code that doesn't use the run loop.
NSTabView and NSTabViewItem
Classes for displaying multiple views using tabs.
NSOutlineView
A subclass of NSTableView that implements an outline representation of hierarchical data. Like NSTableView and NSBrowser objects, NSOutlineView objects use a data source (separate from the delegate) to display the data lazily.
NSColor
New factory methods create objects that represent additional user interface colors.
NSColorPanel
As does the Font panel, the Color panel now has a Set button. When clicked,
it sends a changeColor:
message down the responder chain. See the NSColorPanel documentation for
details.
NSFont
The systemFontOfSize:
and boldSystemFontOfSize:
methods have been deprecated in favor of the other factory methods returning
user-chosen fonts. The function NSConvertGlyphsToPackedGlyphs() was added to allow
you to convert an array of NSGlyphs to "packed" glyphs, suitable for
passing to PostScript.
NSImage and NSBitmapImageRep
NSImage and NSBitmapImageRep can now read GIF, JPEG, and PNG images directly (that is, without the aid of filter services). JPEG and PNG writing is also supported; GIF writing is planned for a future release. Some APIs were added to NSBitmapImageRep to provide support for features found in these image file types.
NSBezierPath and NSAffineTransform
These two classes help provide a more complete abstraction in the Application Kit framework layer for graphics operations. NSBezierPath enables standard operations with lines, user-defined paths, and arrays of glyphs, such as stroking, filling, and clipping. It also provides simple bounds computation and hit detection methods. NSAffineTransform provides an abstraction for the graphics transformation matrix.
NSGraphicsContext
The abstract superclass for NSDPSContext, this class provides methods to save and restore the graphics state and to change the current graphics context.
NSGraphics (Java)
NSGraphics has three class methods that do not work correctly in DR2 (calling them has no effect):
fillRectList(NSRect[])
fillRectListWithColors(NSRect[], NSColor[])
clipRectList(NSRect[])
Instead of these methods, use the corresponding "inRange" methods:
fillRectList(rects) ==>
fillRectListInRange(rects, new NSRange(0, rects.length))
fillRectListWithColors(rects, color) ==>
fillRectListWithColorsInRange(rects, colors, new NSRange(0, rects.length))
clipRectList(rects) ==> clipRectListInRange(rects, new NSRange(0, rects.length))
NSSplitView
The look and feel of the split view has changed significantly. There's no
dimple, the split bar is thinner, and you get a resize image when the cursor is
over it. You should use the method dividerThickness to determine the
correct thickness of the bar.
NSScreen
The new method visibleFrame
supplies the usable region (without menu or task bar regions) of a given
screen.
Menu and Pop-up Button Classes
Menus and pop-up buttons have changed significantly since OpenStep 4.2. In 4.2, NSMenu and NSMenuItem claimed they were NSObject subclasses, but they were actually subclasses of NSPanel and NSButtonCell. Although the compiler would warn about panel or cell messages being sent to these objects, they would perform as required at run time. In the new implementation, NSMenu and NSMenuItem are true subclasses of NSObject. If your code is sending messages to these objects&emdashwhich assume inheritance from NSPanel and NSButtonCell&emdashit will no longer work.
NSMenu and NSMenuItem include new APIs and functionality. NSMenuItems may
now have titles, key equivalents, images, and state images. NSMenus have a
platform-specific menu representation that is in charge of presenting the menu
to the user and allowing the user to interact with it. On Mach, the menu
representation is an NSMenuView. NSMenuView allows much leeway in the way a
menu works and looks. An NSMenuView uses NSMenuItemCells to draw its items. On
Windows the menu representation class is currently private (NSMenu's menuRepresentation
method will return nil).
The NSMenuItem protocol has been deprecated in favor of the NSMenuItem class. Use the class instead of the protocol, which will be dropped from the Application Kit in a future release. There is now a public NSPopUpButtonCell class. See the Application Kit reference documentation for details of the new APIs.
Some planned features are not yet implemented, such as tear offs and key-equivalent overrides. You should not have to do anything special to prepare your application for these coming features. Context menus are supported in the Developer Release, but only for systems with two-button mice. Support will be added in a later release support for Control-click context menus. Your code should not have to change, but you should be aware that using the control key for your own special mouse features is probably not a good idea since that modifier key will soon have another meaning.
NSSlider
Sliders now support tick marks that identify specific values on the slider continuum. Clicking these tick marks returns the represented value.
NSTextView
NSTextView objects can now read HTML files. A delegate method is provided for following HTML links.
Delegate methods for clicking on cells have been augmented with an argument
to specify the character index of the click; for instance,
textView:clickedOnCell:inRect:atIndex: instead of textView:clickedOnCell:inRect:.
The old delegate methods will continue to work, but you should plan to replace
them with the new ones.
The text system now treats control-L ("form feed") as a container break character. A control-L forces the layout to continue onto the next container. However, the text system also tries to recognize the infinitely-growing container case (which is the usual situation in applications such as TextEdit and Project Builder), and ignores the control-L in these cases.
NSApplication
On non-Windows platforms, an application can now choose to quit when the
last window is closed. If the application delegate responds to applicationShouldTerminateAfterLastWindowClosed:
by returning YES, the application is sent a terminate: message when the last
window is closed.
On Windows systems there has been no change. If the last window of an
application is closed, and if the window contained the application menu, the
application is sent the terminate:
message by default. The delegate can prevent this by responding
NO to applicationShouldTerminateAfterLastWindowClosed:.
NSWindow
Instead of miniaturizing, windows now use a feature called WindowShading: when the user clicks the appropriate window control, the window's content view disappears and just the title bar remains (this can be toggled back to the original state). Windows also have a zoom button, which switches a window between a standard (size-to-fit) size and a user size. The standard size can be set by calls to the delegate.
A document icon in the title bar gives access to the document represented by the window; users can drag and drop the document directly (this replaces the "Alternate-drag from the miniaturize button" model of OPENSTEP 4.2).
NSView
Two new methods in NSView, didAddSubview: and willRemoveSubview:, provide
ways to detect subview list changes.
NSCell and NSButtonCell
These classes now support mixed-state cells. You can enable this feature
with the
setAllowsMixedState: method, which allows the cell to be in
NSMixedState mode in addition to NSOnState and NSOffState. In addition, various
bezel styles have been added to support the range of button styles available on
the Mac:
(Although the header file refers to NSNeXTBezelStyle, NSPushButtonBezelStyle, NSSmallIconButtonBezelStyle, NSMediumIconButtonBezelStyle, and NSLargeIconButtonBezelStyle, these styles are obsolete and should not be used.)
Java
The Developer release contains an alpha version of the Java APIs for the Yellow Box. By using these APIs you can access virtually all classes and protocols of the Application Kit and Foundation frameworks. However, since this is an alpha version, these APIs are not yet complete and will most likely change before the next release.
Interface Style
The constant NSMacintoshInterfaceStyle has been added to represent the MacOS user interface. NSNextStepInterfaceStyle has been removed.
When creating resources, use the suffixes "-macintosh" and
"-windows" to indicate any resources that are specific to a
particular interface style. The base resource must be available (for instance, foo.nib); all
the other interface-style specific ones (such as foo-windows.nib) are optional.
This is a feature of NSBundle, and will work with any resource, not just nibs.
This section is provided as a quick guide to developers converting applications from NextStep 3.x to the Yellow Box. OpenStep 4.2 was the last release shipped by NeXT before the Apple purchase.
OpenStep: Release 4.0 brings numerous API changes to the AppKit
relative to Release 3.3. Tools and scripts provided to convert a 3.x
application to OpenStep are included with the 4.x releases, in /NextLibrary/Documentation/NextDev/Conversion/ConversionGuide....
New Text System: Release 4.0 includes a new text system composed of several different classes: NSTextView (front-end UI), NSTextStorage and NSAttributedString (back-end text storage), NSLayoutManager (management of text layout process and info), and NSTextContainer (description of text flow areas). These classes provide an open, powerful interface and allow text editing in multiple languages, using the Unicode standard.
FileWrapper: NSFileWrapper, a new class, provides support for the concept of a document wrapper (like a .rtfd or ....nib). It handles reading and writing file packages in the file system as well as serializing them for use with the Pasteboard.
TableView: DBKit's table view class has been completely rewritten and moved into the AppKit as NSTableView. All four classes making up the new TableView are public and fully subclassable.
Keyboard UI: Keyboard access is now provided to most of the controls in the AppKit.
Formatting and Validation: Cells may now be assigned arbitrary object values, which are converted into presentation strings by associated formatter objects. This allows the developer to directly set an NSDate, for instance, as the value of a cell. The cell's associated date formatter will present a localized string representation of the date to the user. The formatter objects, along with control delegates, can also perform validation on user-entered data, thereby restricting entries to valid ranges or quantities.
Rich Text in Cells: NSCell and subclasses can now display and edit rich text. The rich text is specified via instances of NSAttributedString. The new formatting/validation API also includes support for attributed strings.
RulerView: NSRulerView is designed as a general-purpose ruler that can be associated with any scroll view and used by any view that's in the scroll view. It supports both horizontal and vertical rulers, allows arbitrary markers along the rule, and can accept an accessory view.
System Colors: New API has been added to access system-defined colors, such as the color of buttons, controls, text and text selection colors. On Windows, where the user can change the system colors at any point, these colors will change at runtime to match the user's selection.
Image: NSImage now understands the bmp, ico, and cur image formats. ico and cur files with multiple images will be loaded as images with multiple representations. Typically these representations will have different sizes (unlike multiple-representation tiffs, which have different depths); by default, NSImage will choose the largest image when compositing.
NSApplicationMain: The AppKit now provides a function NSApplicationMain() to take care of the initialization and startup of your application. This function is declared in NSApplication.h.
ObjectLinks: ObjectLinks have been removed from the OpenStep specification, and in general the feature is not supported in OpenStep for Mach or Windows.
Help System: The AppKit's Help API has changed significantly. NSHelpPanel has been obsoleted in favor of a new class, NSHelpManager, which provides a more platform-independent approach to presenting both context-sensitive and comprehensive help.
ComboBox: NSComboBox class has been added to the Application Kit. It offers functionality that is similar to the Combo Box control used in the Microsoft Windows user interface.
Splash Screen: OpenStep for Windows now provides support for a
"splash" screen in applications; this is basically a panel that comes
up with a static image as the application is launched. To use this feature,
simply provide an 8-bit uncompressed bitmap (.bmp) image named Splash.bmp as
a resource in your application. You can make it localizable if you wish (thus
the image can be either in appname.app/Resources/
or appname.app/Resources/language.lproj/)
NSApplication: By default, on OpenStep for Windows, only a single
copy of an application will be launched. If you wish to run multiple copies,
you should use specify a value of NO to the -NSUseRunningCopy command line option.
In addition, all command-line options that are not defaults options (meaning a
pair of arguments where the first one starts with a "-") are now
treated as file names to be opened, as if they were prefixed with -NSOpen. As a
result of these two changes, you can now associate documents with OpenStep
applications on Windows simply by specifying the location of the application.
The default command line provided by the Explorer suffices to open documents
and also to connect to a running copy of the application, if there is one.
Window edited status: In OpenStep for Windows, an asterisk in a window's title bar indicates that the associated document has been edited.
Tracking rectangles: Tracking rectangles are now implemented on Windows.
NSWindow frame vs content rect: On Windows, the frameRect and contentRect of an NSWindow are currently the same size. Thus the frameRect of an NSWindow does not include the title bar, menu bar, resize border, and so on (but does on Mach). Also, the contentView while a window is miniaturized is an NSImageView, not the original contentView. The contentView is restored when the window is deminiaturized.
NSTextView: On Windows, to allow entering a character without an
appropriate keyboard, you can now use the Alternate key in conjunction with the
digit keys from the keypad. While holding down the Alternate key, type the
index of the desired character in the encoding of the current font (in most
cases this will be the NEXTSTEP encoding). The appropriate character will be
inserted into the text when the Alternate key is released.
SplitView: NSSplitView now supports horizontal as well vertical splits.
ToolTips: It's now possible to add "tooltips" (short help messages that pop up as the user holds the mouse cursor over an item) to views. You can do this programmatically or by using Interface Builder's Help panel.
Text Hyphenation and Justification: The text object now supports full justification and hyphenation, with a fairly basic API.
ComboBox cell: There is now a public NSComboBoxCell class. This feature allows you to use combo boxes in table views, among other places.
Hiding applications on Windows: Support for the "hide application" command has been added to OpenStep for Windows. The default menu item for this is Minimize All in the Windows menu (with Control-h as the key equivalent). The Application Kit adds this item automatically if it is not in the menu.
CMYK archiving problem: A bug in decodeNXColor
that caused CMYK colors from 3.x archives to be read incorrectly in 4.0
and 4.1 has been fixed. (The colors were way off base; instead of C, M, Y, K,
the values 1-C, 1-M, 1-Y, and 1-K were used.)